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Introduction to This Guide 



This document provides information to developers on the use of the 
STREAMS mechanism at user and kernel levels. 

STREAMS was incorporated in UNIX System V Release 3 to augment the 
existing character input/output (I/O) mechanism and to support development of 
communication services. The STREAMS Programmers Guide (P-H) includes 
detailed information, with various examples, on the development methods and 
design philosophy of all aspects of STREAMS. 

This guide is organized into two parts. Part 1: Applications Programming, 
describes the development of user level applications. Part 2: Module and Driver 
Programming, describes the STREAMS kernel facilities for development of 
modules and drivers. Although chapter numbers are consecutive, the two parts 
are independent. Working knowledge of the STREAMS Primer (P-H) is 
assumed. 
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STREAMS Overview 



This section reviews the STREAMS mechanism. STREAMS is a general, 
flexible facility and a set of tools for development of UNIX system communica- 
tion services. It supports the implementation of services ranging from complete 
networking protocol suites to individual device drivers. STREAMS defines stand- 
ard interfaces for character input/output within the kernel, and between the ker- 
nel and the rest of the UNIX system. The associated mechanism is simple and 
open-ended. It consists of a set of system calls, kernel resources and kernel rou- 
tines. 

The standard interface and mechanism enable modular, portable development 
and easy integration of higher performance network services and their com- 
ponents. STREAMS provides a framework: It does not impose any specific net- 
work architecture. The STREAMS user interface is upwardly compatible with 
the character I/O user interface, and both user interfaces are available in UNIX 
System V Release 3 and subsequent releases. 

A Stream is a full-duplex processing and data transfer path between a 
STREAMS driver in kernel space and a process in user space (see Figure 1). In 
the kernel, a Stream is constructed by linking a stream head, a driver and zero or 
more modules between the stream head and driver. The Stream head is the end 
of the Stream closest to the user process. Throughout this guide, the word 
"STREAMS" will refer to the mechanism and the word "Stream" will refer to the 
path between a user and a driver. 

A STREAMS driver may be a device driver that provides the services of an 
external I/O device, or a software driver, commonly referred to as a pseudo-device 
driver, that performs functions internal to a Stream. The Stream head provides 
the interface between the Stream and user processes. Its principal function is to 
process STREAMS-related user system calls. 

Data are passed between a driver and the Stream head in messages. Mes- 
sages that are passed from the Stream head toward the driver are said to travel 
downstream. Similarly, messages passed in the other direction travel upstream. 
The Stream head transfers data between the data space of a user process and 
STREAMS kernel data space. Data to be sent to a driver from a user process 
are packaged into STREAMS messages and passed downstream. When a mes- 
sage containing data arrives at the Stream head from downstream, the message is 
processed by the Stream head, which copies the data into user buffers. 
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STREAMS Overview 




External 

Interface 



Figure 1: Basic Stream 



Within a Stream, messages are distinguished by a type indicator. Certain 
message types sent upstream may cause the Stream head to perform specific 
actions, such as sending a signal to a user process. Other message types are 
intended to carry information within a Stream and are not directly seen by a user 
process. 

One or more kernel-resident modules may be inserted into a Stream between 
the Stream head and driver to perform intermediate processing of data as it 
passes between the Stream head and driver. STREAMS modules are dynami- 
cally interconnected in a Stream by a user process. No kernel programming, 
assembly, or link editing is required to create the interconnection. 
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Development Facilities 



General and STREAMS-specific system calls provide the user level facilities 
required to implement application programs. This system call interface is 
upwardly compatible with the character I/O facilities. The open (2) system call 
will recognize a STREAMS file and create a Stream to the specified driver. A 
user process can receive and send data on STREAMS files using read (2) and 
write (2) in the same manner as with character files. The ioctl(2) system call 
enables users to perform functions specific to a particular device and a set of gen- 
eric STREAMS ioctl commands [see streamio(7)] support a variety of functions 
for accessing and controlling Streams. A close (2) will dismantle a Stream. 

In addition to the generic ioctl commands, there are STREAMS-specific sys- 
tem calls to support unique STREAMS facilities. The poll (2) system call enables 
a user to poll multiple Streams for various events. The putmsg(2) and getmsg(2) 
system calls enable users to send and receive STREAMS messages, and are suit- 
able for interacting with STREAMS modules and drivers through a service inter- 
face. 

STREAMS provides kernel facilities and utilities to support development of 
modules and drivers. The Stream head handles most system calls so that the 
related processing does not have to be incorporated in a module and driver. The 
configuration mechanism allows modules and drivers to be incorporated into the 
system. 

Examples are used throughout both parts of this document to highlight the 
most important and common capabilities of STREAMS. The descriptions are not 
meant to be exhaustive. For simplicity, the examples reference fictional drivers 
and modules. 

Appendix C provides the reference for STREAMS kernel utilities. 

STREAMS system calls are specified in Section 2 of the Programmer’s Reference 
Manual (P-H). STREAMS utilities are specified in Section 1M of the System 
Administrator’s Reference Manual (AT&T). STREAMS-specific ioctl calls are 
specified in streamio(7) of the System Administrator’s Reference Manual 
(AT&T). The modules and drivers available with UNIX System V Release 3 are 
described in Section 7 of the System Administrator’s Reference Manual 
(AT&T). 
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PARTI: APPLICATION PROGRAMMING 



Introduction to Part 1 

Part 1 of the guide, Application Programming, provides detailed information, 
with various examples, on the user interface to STREAMS facilities. It is 
intended for application programmers writing to the STREAMS system call inter- 
face. Working knowledge of UNIX system user programming, data communica- 
tion facilities, and the STREAMS Primer is assumed. The organization of Part 1 
is as follows: 

■ Chapter 1, Basic Operations, describes the basic operations available for 
constructing, using, and dismantling Streams. These operations are per- 
formed using open (2), close (2), read (2), write (2), and ioctl(2). 

■ Chapter 2, Advanced Operations, presents advanced facilities provided by 
STREAMS, including: poll(2), a user level I/O polling facility; asynchro- 
nous I/O processing support; and a new facility for sampling drivers for 
available resources. 

■ Chapter 3, Multiplexed Streams, describes the construction of sophisti- 
cated, multiplexed Stream configurations. 

■ Chapter 4, Message Handling, describes how users can process 
STREAMS messages using putmsg(2) and getmsg(2) in the context of a 
service interface example. 
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CHAPTER 1: BASIC OPERATIONS 



A Simple Stream 

This chapter describes the basic set of operations for manipulating 
STREAMS entities. 

A STREAMS driver is similar to a character I/O driver in that it has one or 
more nodes associated with it in the file system and it is accessed using the open 
system call. Typically, each file system node corresponds to a separate minor 
device for that driver. Opening different minor devices of a driver will cause 
separate Streams to be connected between a user process and the driver. The file 
descriptor returned by the open call is used for further access to the Stream. If 
the same minor device is opened more than once, only one Stream will be created; 
the first open call will create the Stream, and subsequent open calls will return a 
file descriptor that references that Stream. Each process that opens the same 
minor device will share the same Stream to the device driver. 

Once a device is opened, a user process can send data to the device using the 
write system call and receive data from the device using the read system call. 
Access to STREAMS drivers using read and write is compatible with the charac- 
ter I/O mechanism. 

The close system call will close a device and dismantle the associated Stream. 

The following example shows how a simple Stream is used. In the example, 
the user program interacts with a generic communications device that provides 
point-to-point data transfer between two computers. Data written to the device is 
transmitted over the communications line, and data arriving on the line can be 
retrieved by reading it from the device. 
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A Simple Stream 




In the example, /dev/commOl identifies a minor device of the communications 
device driver. When this file is opened, the system recognizes the device as a 
STREAMS device and connects a Stream to the driver. Figure 1-1 shows the 
state of the Stream following the call to open. 
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A Simple Stream 




Figure 1-1: Stream to Communications Driver 



This example illustrates a user reading data from the communications device 
and then writing the input back out to the same device. In short, this program 
echoes all input back over the communications line. The example assumes that a 
user is sending data from the other side of the communications line. The program 
reads up to 1024 bytes at a time, and then writes the number of bytes just read. 

The read call returns the available data, which may contain fewer than 1024 
bytes. If no data are currently available at the Stream head, the read call blocks 
until data arrive. 

Similarly, the write call attempts to send count bytes to /dev/commOI. How- 
ever, STREAMS implements a flow control mechanism that prevents a user from 
flooding a device driver with data, thereby exhausting system resources. If the 
Stream exerts flow control on the user, the write call blocks until the flow control 
has been relaxed. The call will not return until it has sent count bytes to the 
device, exit (2) is called to terminate the user process. This system call also 
closes all open files, thereby dismantling the Stream in this example. 
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Inserting Modules 

An advantage of STREAMS over the existing character I/O mechanism 
stems from the ability to insert various modules into a Stream to process and 
manipulate data that passes between a user process and the driver. The following 
example extends the previous communications device echoing example by inserting 
a module in the Stream to change the case of certain alphabetic characters. The 
case converter module is passed an input string and an output string by the user. 
Any incoming data (from the driver) is inspected for instances of characters in 
the module’s input string and the alphabetic case of all matching characters is 
changed. Similar actions are taken for outgoing data using the output string. 

The necessary declarations for this program are shown below: 




The first step is to establish a Stream to the communications driver and insert 
the case converter module. The following sequence of system calls accomplishes 
this: 
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Inserting Modules 




The I_PUSH ioctl call directs the Stream head to insert the case converter 
module between the driver and the Stream head, creating the Stream shown in 
Figure 1-2. As with any driver, this module resides in the kernel and must have 
been configured into the system before it was booted. I PUSH is one of several 
generic STREAMS ioctl commands that enable a user to access and control indi- 
vidual Streams [see streamio(7)]. 
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Inserting Modules 





Figure 1-2: Case Converter Module 



An important difference between STREAMS drivers and modules is illus- 
trated here. Drivers are accessed through a node or nodes in the file system and 
may be opened just like any other device. Modules, on the other hand, do not 
occupy a file system node. Instead, they are identified through a separate naming 
convention, and are inserted into a Stream using I_PUSH. The name of a module 
is defined by the module developer, and is typically included on the manual page 
describing the module (manual pages describing STREAMS drivers and modules 
are found in section 7 of the System Administrator s Reference Manual). 

Modules are pushed onto a Stream and removed from a Stream in Last-In- 
First-Out (LIFO) order. Therefore, if a second module was pushed onto this 
Stream, it would be inserted between the Stream head and the case converter 
module. 
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Module and Driver Control 



The next step in this example is to pass the input string and output string to 
the case converter module. This can be accomplished by issuing ioctl calls to the 
case converter module as follows: 




ioctl requests are issued to STREAMS drivers and modules indirectly, using 
the I_STR ioctl call [see streamio(7)]. The argument to I_STR must be a pointer 
to a strioctl structure, which specifies the request to be made to a module or 
driver. This structure is defined in <stropts.h> and has the following format: 
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Module and Driver Control 



struct strioctl { 



int 


ic and; 


/* ioctl request */ 


int 


ic timout; 


/* ACK/NAK timeout */ 


int 


ic len; 


/* length of data argument */ 


char 


*ic dp; 


/* ptr to data argument */ 



} , 

where iccmd identifies the command intended for a module or driver, ictimout 
specifies the number of seconds an I_STR request should wait for an ack- 
nowledgement before timing out, icjen is the number of bytes of data to accom- 
pany the request, and icdp points to that data. 

I_STR is intercepted by the Stream head, which packages it into a message, 
using information contained in the strioctl structure, and sends the message down- 
stream. The request will be processed by the module or driver closest to the 
Stream head that understands the command specified by ic cmd. The ioctl call 
will block up to icjimout seconds, waiting for the target module or driver to 
respond with either a positive or negative acknowledgement message. If an ack- 
nowledgement is not received in icjimout seconds, the ioctl call will fail. 

I_STR is actually a nested request; the Stream head intercepts I_STR and 
then sends the driver or module request (as specified in the strioctl structure) 
downstream. Any module that does not understand the command in ic_cmd will 
pass the message further downstream. Eventually, the request will reach the tar- 
get module or driver, where it is processed and acknowledged. If no module or 
driver understands the command, a negative acknowledgement will be generated 
and the ioctl call will fail. 

In the example, two separate commands are sent to the case converter 
module. The first contains the conversion string for input data, and the second 
contains the conversion string for output data. The ic cmd field is set to indicate 
whether the command is setting the input or output conversion string. For each 
command, the value of icjimout is set to zero, which specifies the system default 
timeout value of 15 seconds. Also, a data argument that contains the conversion 
string accompanies each command. The ic_dp field points to the beginning of 
each string, and ic len is set to the length of the string. 
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Module and Driver Control 



NOTE 



Only one I STR request can be active on a STREAM at one time. Further 
requests will block until the active I_STR request is acknowledged and the sys- 
tem call completes. 



The strioctl structure is also used to retrieve the results, if any, of an ISTR 
request. If data is returned by the target module or driver, ic_dp must point to a 
buffer large enough to hold that data, and icjen will be set on return to indicate 
the amount of data returned. 

The remainder of this example is identical to the previous example: 




The case converter module will convert the specified input characters to lower 
case, and the corresponding output characters to upper case. Notice that the case 
conversion processing was realized with no change to the communications driver. 

As with the previous example, the exit system call will dismantle the Stream 
before terminating the process. The case converter module will be removed from 
the Stream automatically when it is closed. Alternatively, modules may be 
removed from a Stream using the I POP ioctl call described in streamio(7). This 
call removes the topmost module on the Stream, and enables a user process to 
alter the configuration of a Stream dynamically, by pushing and popping modules 
as needed. 
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Module and Driver Control 



A few of the important ioctl requests supported by STREAMS have been dis- 
cussed. Several other requests are available to support operations such as deter- 
mining if a given module exists on the Stream, or flushing the data on a Stream. 
These requests are described fully in streamio(7). 
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CHAPTER 2: ADVANCED OPERATIONS 



Advanced Input/Output Facilities 

The traditional input/output facilities— open, close, read, write, and ioctl— 
have been discussed, but STREAMS supports new user capabilities that will be 
described in the remaining chapters of this guide. This chapter describes a facil- 
ity that enables a user process to poll multiple Streams simultaneously for various 
events. Also discussed is a signaling feature that supports asynchronous I/O pro- 
cessing. Finally, this chapter presents a new mechanism for finding available 
minor devices, called clone open. 



ADVANCED OPERATIONS 13 




Input/Output Polling 

The poll (2) system call provides users with a mechanism for monitoring input 
and output on a set of file descriptors that reference open Streams. It identifies 
those Streams over which a user can send or receive data. For each Stream of 
interest users can specify one or more events about which they should be notified. 
These events include the following: 

POLLIN Input data is available on the Stream associated with the given 
file descriptor. 

POLLPRI A priority message is available on the Stream associated with the 
given file descriptor. Priority messages are described in the sec- 
tion of Chapter 4 entitled "Accessing the Datagram Provider." 

POLLOUT The Stream associated with the given file is writable. That is, 
the Stream has relieved the flow control that would prevent a 
user from sending data over that Stream. 

poll will examine each file descriptor for the requested events and, on return, 
will indicate which events have occurred for each file descriptor. If no event has 
occurred on any polled file descriptor, poll blocks until a requested event or 
timeout occurs. The specific arguments to poll are the following: 

■ an array of file descriptors and events to be polled 

■ the number of file descriptors to be polled 

■ the number of milliseconds poll should wait for an event if no events are 
pending (-1 specifies wait forever) 

The following example shows the use of poll. Two separate minor devices of 
the communications driver presented earlier are opened, thereby establishing two 
separate Streams to the driver. Each Stream is polled for incoming data. If data 
arrives on either Stream, it is read and then written back to the other Stream. 
This program extends the previous echoing example by sending echoed data over 
a separate communications line (minor device) . The steps needed to establish 
each Stream are as follows: 
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Input/Output Polling 




The variable pollfds is declared as an array of pollfd structures, where this 
structure is defined in <poll.h> and has the following format: 

struct pollfd { 
int fd; 
short events ; 

short revents ; 

} 

For each entry in the array, fd specifies the file descriptor to be polled and 
events is a bitmask that contains the bitwise inclusive OR of events to be polled 
on that file descriptor. On return, the revents bitmask will indicate which of the 
requested events has occurred. 



/* file descriptor */ 
/* requested events */ 
/* returned events */ 
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Input/Output Polling 



The example opens two separate minor devices of the communications driver 
and initializes the pollfds entry for each. The remainder of the example uses poll 
to process incoming data as follows: 
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Input/Output Polling 



The user specifies the polled events by setting the events field of the pollfd 
structure to POLLIN. This requested event directs poll to notify the user of any 
incoming data on each Stream. The bulk of the example is an infinite loop, where 
each iteration will poll both Streams for incoming data. 

The second argument to poll specifies the number of entries in the pollfds 
array (2 in this example). The third argument is a timeout value indicating the 
number of milliseconds poll should wait for an event if none has occurred. On a 
system where millisecond accuracy is not available, timeout is rounded up to the 
nearest legal value available on that system. Here, the value of timeout is -1, 
specifying that poll should block indefinitely until a requested event occurs or until 
the call is interrupted. 

If poll succeeds, the program looks at each entry in pollfds. If revents is set 
to 0, no event has occurred on that file descriptor. If revents is set to POLLIN, 
incoming data is available. In this case, all available data is read from the polled 
minor device and written to the other minor device. 

If revents is set to a value other than 0 or POLLIN, an error event must have 
occurred on that Stream, because the only requested event was POLLIN. The 
following error events are defined for poll. These events may not be polled for by 
the user, but will be reported in revents whenever they occur. As such, they are 
only valid in the revents bitmask: 

POLLERR A fatal error has occurred in some module or driver on the 
Stream associated with the specified file descriptor. Further 
system calls will fail. 

POLLHUP A hangup condition exists on the Stream associated with the 
specified file descriptor. 

POLLNVAL The specified file descriptor is not associated with an open 
Stream. 

The example attempts to process incoming data as quickly as possible. How- 
ever, when writing data to a Stream, the write call may block if the Stream is 
exerting flow control. To prevent the process from blocking, the minor devices of 
the communications driver were opened with the ONDELAY flag set. If flow 
control is exerted and O NDELAY is set, write will not be able to send all the 
data. This can occur if the communications driver is unable to keep up with the 
user’s rate of data transmission. If the Stream becomes full, the number of bytes 
write sends will be less than the requested count. For simplicity, the example 
ignores the data if the Stream becomes full, and a warning is printed to stderr. 
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Input/Output Polling 



This program will continue until an error occurs on a Stream, or until the 
process is interrupted. 
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Asynchronous Input/Output 

The poll system call described above enables a user to monitor multiple 
Streams in a synchronous fashion. The poll call normally blocks until an event 
occurs on any of the polled file descriptors. In some applications, however, it is 
desirable to process incoming data asynchronously. For example, an application 
may wish to do some local processing and be interrupted when a pending event 
occurs. Some time-critical applications cannot afford to block, but must have 
immediate indication of success or failure. 

A new facility is available for use with STREAMS that enables a user pro- 
cess to request a signal when a given event occurs on a Stream. When used with 
poll, this facility enables applications to asynchronously monitor a set of file 
descriptors for events. 

The ISETSIG ioctl call [see streamio(7)] is used to request that a SIG- 
POLL signal be sent to a user process when a specific event occurs. Listed below 
are the events for which an application may be signaled: 

S INPUT Data has arrived at the Stream head, and no data existed at 
the Stream head when it arrived. 

SHIPRI A priority STREAMS message has arrived at the Stream 

head. 

S OUTPUT The Stream is no longer full and can accept output. That is, 
the Stream has relieved the flow control that would prevent a 
user from sending data over that Stream. 

S_MSG A special STREAMS signal message that contains a SIG- 

POLL signal has reached the front of the Stream head input 
queue. This message may be sent by modules or drivers to 
generate immediate notification of data or events to follow. 

The polling example could be written to process input from each communica- 
tions driver minor device by issuing I_SETSIG to request a signal for the 
S_INPUT event on each Stream. The signal catching routine could then call poll 
to determine on which Stream the event occurred. The default action for SIG- 
POLL is to terminate the process. Therefore, the user process must catch the sig- 
nal using signal(2). SIGPOLL will only be sent to processes that request the sig- 
nal using I SETSIG. 
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Clone Open 



In the earlier examples, each user process connected a Stream to a driver by 
opening a particular minor device of that driver. Often, however, a user process 
wants to connect a new Stream to a driver regardless of which minor device is 
used to access the driver. 

In the past, this typically forced the user process to poll the various minor 
device nodes of the driver for an available minor device. To alleviate this task, a 
facility called clone open is supported for STREAMS drivers. If a STREAMS 
driver is implemented as a cloneable device, a single node in the file system may 
be opened to access any unused minor device. This special node guarantees that 
the user will be allocated a separate Stream to the driver on every open call. 

Each Stream will be associated with an unused minor device, so the total number 
of Streams that may be connected to a cloneable driver is limited by the number 
of minor devices configured for that driver. 

The clone device may be useful, for example, in a networking environment 
where a protocol pseudo-device driver requires each user to open a separate 
Stream over which it will establish communication. Typically, the users would 
not care which minor device they used to establish a Stream to the driver. 

Instead, the clone device can find an available minor device for each user and 
establish a unique Stream to the driver. Chapter 3 describes this type of trans- 
port protocol driver. 



NOTE 



A user program has no control over whether a given driver supports the clone 
open. The decision to implement a STREAMS driver as a cloneable device is 
made by the designers of the device driver. 
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CHAPTER 3: MULTIPLEXED STREAMS 



Multiplexor Configurations 

In the earlier chapters, Streams were described as linear connections of 
modules, where each invocation of a module is connected to at most one upstream 
module and one downstream module. While this configuration is suitable for 
many applications, others require the ability to multiplex Streams in a variety of 
configurations. Typical examples are terminal window facilities, and internet- 
working protocols (which might route data over several subnetworks) . 

An example of a multiplexor is one that multiplexes data from several upper 
Streams over a single lower Stream, as shown in Figure 3-1. An upper Stream is 
one that is upstream from a multiplexor, and a lower Stream is one that is down- 
stream from a multiplexor. A terminal windowing facility might be implemented 
in this fashion, where each upper Stream is associated with a separate window. 




Figure 3-1: Many-to-one Multiplexor 



A second type of multiplexor might route data from a single upper Stream to 
one of several lower Streams, as shown in Figure 3-2. An internetworking proto- 
col could take this form, where each lower Stream links the protocol to a different 
physical network. 
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Multiplexor Configurations 




Figure 3-2: One-to-many Multiplexor 



A third type of multiplexor might route data from one of many upper 
Streams to one of many lower Streams, as shown in Figure 3-3. 




Figure 3-3: Many-to-many Multiplexor 
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Multiplexor Configurations 



A STREAMS mechanism is available that supports the multiplexing of 
Streams through special pseudo-device drivers. Using a linking facility, users can 
dynamically build, maintain, and dismantle each of the above multiplexed Stream 
configurations. In fact, these configurations can be further combined to form 
complex, multi-level multiplexed Stream configurations. 

The remainder of this chapter describes multiplexed Stream configurations in 
the context of an example (see Figure 3-4). In this example, an internetworking 
protocol pseudo-device driver (IP) is used to route data from a single upper 
Stream to one of two lower Streams. This driver supports two STREAMS con- 
nections beneath it to two distinct sub-networks. One sub-network supports the 
IEEE 802.3 standard for the CSMA/CD medium access method. The second 
sub-network supports the IEEE 802.4 standard for the token-passing bus medium 
access method. 

The example also presents a transport protocol pseudo-device driver (TP) that 
multiplexes multiple virtual circuits (upper Streams) over a single Stream to the 
IP pseudo-device driver. 
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Building a Multiplexor 

Figure 3-4 shows the multiplexing configuration to be created. This 
configuration will enable users to access the services of the transport protocol. To 
free users from the need to know about the underlying protocol structure, a user- 
level daemon process will build and maintain the multiplexing configuration. 

Users can then access the transport protocol directly by opening the TP driver 
device node. 




Figure 3-4: Protocol Multiplexor 
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Building a Multiplexor 



The following example shows how this daemon process sets up the protocol 
multiplexor. The necessary declarations and initialization for the daemon pro- 
gram are as follows: 




This multi-level multiplexed Stream configuration will be built from the bot- 
tom up. Therefore, the example begins by constructing the IP multiplexor. This 
multiplexing pseudo-device driver is treated like any other software driver. It 
owns a node in the UNIX file system and is opened just like any other 
STREAMS device driver. 

The first step is to open the multiplexing driver and the 802.4 driver, creating 
separate Streams above each driver as shown in Figure 3-5. The Stream to the 
802.4 driver may now be connected below the multiplexing IP driver using the 
I LINK ioctl call. 
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Building a Multiplexor 



daemon 



User Space 
Kernel Space 



802.4 


ip 


Driver 


Driver 



Figure 3-5: Before Link 



The sequence of instructions to this point is: 
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Building a Multiplexor 



I_LINK takes two file descriptors as arguments. The first file descriptor, 
fdjp , must reference the Stream connected to the multiplexing driver, and the 
second file descriptor, fd_802_4 , must reference the Stream to be connected below 
the multiplexor. Figure 3-6 shows the state of these Streams following the 
I_LINK call. The complete Stream to the 802.4 driver has been connected below 
the IP driver, including the Stream head. The Stream head of the 802.4 driver 
will be used by the IP driver to manage the multiplexor. 



daemon 




Figure 3-6: IP Multiplexor After First Link 



IJLINK will return an integer value, called a mux id, which is used by the 
multiplexing driver to identify the Stream just connected below it. This mux id is 
ignored in the example, but may be useful for dismantling a multiplexor or rout- 
ing data through the multiplexor. Its significance is discussed later. 
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Building a Multiplexor 



The following sequence of system calls is used to continue building the inter- 
networking multiplexor (IP): 




All links below the IP driver have now been established, giving the 
configuration in Figure 3-7. 
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Building a Multiplexor 




Figure 3-7: IP Multiplexor 



The Stream above the multiplexing driver used to establish the lower connec- 
tions is the controlling Stream and has special significance when dismantling the 
multiplexing configuration, as will be illustrated later in this chapter. The Stream 
referenced by fdjp is the controlling Stream for the IP multiplexor. 



NOTE 



The order in which the Streams in the multiplexing configuration are opened is 
unimportant. If, however, it is necessary to have intermediate modules in the 
Stream between the IP driver and media drivers, these modules must be added to 
the Streams associated with the media drivers (using I PUSH) before the media 
drivers are attached below the multiplexor. 



MULTIPLEXED STREAMS 29 








Building a Multiplexor 



The number of Streams that can be linked to a multiplexor is restricted by 
the design of the particular multiplexor. The manual page describing each driver 
(typically found in section 7 of the System Administrator’s Reference Manual) 
should describe such restrictions. However, only one IJLINK operation is allowed 
for each lower Stream; a single Stream cannot be linked below two multiplexors 
simultaneously. 

Continuing with the example, the IP driver will now be linked below the 
transport protocol (TP) multiplexing driver. As seen earlier in Figure 3-4, only 
one link will be supported below the transport driver. This link is formed by the 
following sequence of system calls: 




The multi-level multiplexing configuration shown in Figure 3-8 has now been 
created. 
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Building a Multiplexor 




Figure 3-8: TP Multiplexor 



Because the controlling Stream of the IP multiplexor has been linked below 
the TP multiplexor, the controlling Stream for the new multi-level multiplexor 
configuration is the Stream above the TP multiplexor. 

At this point the file descriptors associated with the lower drivers can be 
closed without affecting the operation of the multiplexor. Closing these file 
descriptors may be necessary when building large multiplexors, so that many 
devices can be linked together without exceeding the UNIX system limit on the 
number of simultaneously open files per process. If these file descriptors are not 
closed, all subsequent read, write, ioctl, poll, getmsg, and putmsg system calls 
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Building a Multiplexor 

issued to them will fail. That is because I LINK associates the Stream head of 
each linked Stream with the multiplexor, so the user may not access that Stream 
directly for the duration of the link. 

The following sequence of system calls will complete the multiplexing daemon 
example: 




Figure 3-4 shows the complete picture of the multi-level protocol multiplexor. 
The transport driver is designed to support several, simultaneous virtual circuits, 
where these virtual circuits map one-to-one to Streams opened to the transport 
driver. These Streams will be multiplexed over the single Stream connected to 
the IP multiplexor. The mechanism for establishing multiple Streams above the 
transport multiplexor is actually a by-product of the way in which Streams are 
created between a user process and a driver. By opening different minor devices 
of a STREAMS driver, separate Streams will be connected to that driver. Of 
course, the driver must be designed with the intelligence to route data from the 
single lower Stream to the appropriate upper Stream. 

Notice in Figure 3-4 that the daemon process maintains the multiplexed 
Stream configuration through an open Stream (the controlling Stream) to the 
transport driver. Meanwhile, other users can access the services of the transport 
protocol by opening new Streams to the transport driver; they are freed from the 
need for any unnecessary knowledge of the underlying protocol configurations and 
sub-networks that support the transport service. 
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Building a Multiplexor 



Multi-level multiplexing configurations, such as the one presented in the 
above example, should be assembled from the bottom up. That is because 
STREAMS does not allow ioctl requests (including I_LINK) to be passed 
through higher multiplexing drivers to reach the desired multiplexor; they must be 
sent directly to the intended driver. For example, once the IP driver is linked 
under the TP driver, ioctl requests cannot be sent to the IP driver through the TP 
driver. 
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Dismantling a Multiplexor 

Streams connected to a multiplexing driver from above with open, can be dis- 
mantled by closing each Stream with close. In the protocol multiplexor, these 
Streams correspond to the virtual circuit Streams above the TP multiplexor. The 
mechanism for dismantling Streams that have been linked below a multiplexing 
driver is less obvious, and is described below in detail. 

The IJJNLINK ioctl call is used to disconnect each multiplexor link below a 
multiplexing driver individually. This command takes the following form: 

ioctl(fd, I_UNLINK, mux_id) ; 

where fd is a file descriptor associated with a Stream connected to the multiplex- 
ing driver from above, and mux id is the identifier that was returned by ILINK 
when a driver was linked below the multiplexor. Each lower driver may be 
disconnected individually in this way, or a special mux id value of -1 may be used 
to disconnect all drivers from the multiplexor simultaneously. 

In the multiplexing daemon program presented earlier, the multiplexor is 
never explicitly dismantled. That is because all links associated with a multiplex- 
ing driver are automatically dismantled when the controlling Stream associated 
with that multiplexor is closed. Because the controlling Stream is open to a 
driver, only the final call of close for that Stream will close it. In this case, the 
daemon is the only process that has opened the controlling Stream, so the multi- 
plexing configuration will be dismantled when the daemon exits. 

For the automatic dismantling mechanism to work in the multi-level, multi- 
plexed Stream configuration, the controlling Stream for each multiplexor at each 
level must be linked under the next higher level multiplexor. In the example, the 
controlling Stream for the IP driver was linked under the TP driver. This resu- 
lted in a single controlling Stream for the full, multi-level configuration. Because 
the multiplexing program relied on closing the controlling Stream to dismantle the 
multiplexed Stream configuration instead of using explicit I JJNLINK calls, the 
mux id values returned by I LINK could be ignored. 
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Dismantling a Multiplexor 



An important side effect of automatic dismantling on close is that it is not 
possible for a process to build a multiplexing configuration and then exit. That is 
because exit (2) will close all files associated with the process, including the con- 
trolling Stream. To keep the configuration intact, the process must exist for the 
life of that multiplexor. That is the motivation for implementing the example as a 
daemon process. 



MULTIPLEXED STREAMS 35 




Routing Data Through a Multiplexor 

As demonstrated, STREAMS has provided a mechanism for building multi- 
plexed Stream configurations. However, the criteria on which a multiplexor 
routes data is driver dependent. For example, the protocol multiplexor shown in 
the last example might use address information found in a protocol header to 
determine over which sub-network a given packet should be routed. It is the mul- 
tiplexing driver’s responsibility to define its routing criteria. 

One routing option available to the multiplexor is to use the mux id value to 
determine to which Stream data should be routed (remember that each multi- 
plexor link is associated with a mux id) . I LINK passes the mux id value to the 
driver and returns this value to the user. The driver can therefore specify that the 
mux id value must accompany data routed through it. For example, if a multi- 
plexor routed data from a single upper Stream to one of several lower Streams (as 
did the IP driver), the multiplexor could require the user to insert the mux id of 
the desired lower Stream into the first four bytes of each message passed to it. 

The driver could then match the mux id in each message with the mux id of each 
lower Stream, and route the data accordingly. 
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CHAPTER 4: MESSAGE HANDLING 



Service Interface Messages 

A STREAMS message format has been defined to simplify the design of ser- 
vice interfaces. Also, two new system calls, getmsg(2) and putmsg(2) are avail- 
able for sending these messages downstream and receiving messages that are 
available at the Stream head. This chapter describes these system calls in the 
context of a service interface example. First, a brief overview of STREAMS ser- 
vice interfaces is presented. 



Service Interfaces 

A principal advantage of the STREAMS mechanism is its modularity. From 
user level, kernel-resident modules can be dynamically interconnected to imple- 
ment any reasonable processing sequence. This modularity reflects the layering 
characteristics of contemporary network architectures. 

One benefit of modularity is the ability to interchange modules of like func- 
tion. For example, two distinct transport protocols, implemented as STREAMS 
modules, may provide a common set of services. An application or higher layer 
protocol that requires those services can use either module. This ability to substi- 
tute modules enables user programs and higher level protocols to be independent 
of the underlying protocols and physical communication media. 

Each STREAMS module provides a set of processing functions, or services, 
and an interface to those services. The service interface of a module defines the 
interaction between that module and any neighboring modules, and therefore is a 
necessary component for providing module substitution. By creating a well- 
defined service interface, applications and STREAMS modules can interact with 
any module that supports that interface. Figure 4-1 demonstrates this. 
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Service Interface Messages 




Figure 4-1: Protocol Substitution 



By defining a service interface through which applications interact with a 
transport protocol, it is possible to substitute a different protocol below that ser- 
vice interface in a manner completely transparent to the application. In this 
example, the same application can run over the Transmission Control Protocol 
(TCP) and the ISO transport protocol. Of course, the service interface must 
define a set of services common to both protocols. 

The three components of any service interface are the service user, the service 
provider, and the service interface itself, as seen in Figure 4-2. 
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Service Interface Messages 




Figure 4-2: Service Interface 



Typically, a user makes a request of a service provider using some well- 
defined service primitive. Responses and event indications are also passed from 
the provider to the user using service primitives. The service interface is defined 
as the set of primitives that define a service and the allowable state transitions 
that result as these primitives are passed between the user and provider. 
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The Message Interface 

A message format has been defined to simplify the design of service interfaces 
using STREAMS. Each service interface primitive is a distinct STREAMS mes- 
sage that has two parts: a control part and a data part. The control part contains 
information that identifies the primitive and includes all necessary parameters. 

The data part contains user data associated with that primitive. 

An example of a service interface primitive is a transport protocol connect 
request. This primitive requests the transport protocol service provider to estab- 
lish a connection with another transport user. The parameters associated with 
this primitive may include a destination protocol address and specific protocol 
options to be associated with that connection. Some transport protocols also allow 
a user to send data with the connect request. A STREAMS message would be 
used to define this primitive. The control part would identify the primitive as a 
connect request and would include the protocol address and options. The data 
part would contain the associated user data. 

STREAMS enables modules to create these messages and pass them to neigh- 
bor modules. However, the read and write system calls are not sufficient to enable 
a user process to generate and receive such messages. First, read and write are 
byte-stream oriented, with no concept of message boundaries. To support service 
interfaces, the message boundary of each service primitive must be preserved so 
that the beginning and end of each primitive can be located. Also, read and write 
offer only one buffer to the user for transmitting and receiving STREAMS mes- 
sages. If control information and data were placed in a single buffer, the user 
would have to parse the contents of the buffer to separate the data from the con- 
trol information. 

Two new STREAMS system calls are available that enable user processes to 
create STREAMS messages and send them to neighboring kernel modules and 
drivers or receive the contents of such messages from kernel modules and drivers. 
These system calls preserve message boundaries and provide separate buffers for 
the control and data parts of a message. 

The putmsg system call enables a user to create STREAMS messages and 
send them downstream. The user supplies the contents of the control and data 
parts of the message in two separate buffers. Likewise, the getmsg system call 
retrieves such messages from a Stream and places the contents into two user 
buffers. 
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The Message Interface 



The syntax of putmsg is as follows: 

int putmsg (fd, ctlptr, dataptr, flags) 
int fd; 

struct strbuf *ctlptr; 
struct strbuf *dataptr; 
int flags; 

fd identifies the Stream to which the message will be passed, ctlptr and 
dataptr identify the control and data parts of the message, and flags may be used 
to specify that a priority message should be sent. 

The strbuf structure is used to describe the control and data parts of a mes- 
sage, and has the following format: 

struct strbuf { 



int 


maxlen; 


/* maximum buffer length */ 


int 


len; 


/* length of data */ 


char 


*buf ; 


/* pointer to buffer */ 



} 



buf points to a buffer containing the data and len specifies the number of 
bytes of data in the buffer, maxlen specifies the maximum number of bytes the 
given buffer can hold, and is only meaningful when retrieving information into the 
buffer using getmsg. 

The getmsg system call retrieves messages available at the Stream head, and 
has the following syntax: 



int getmsg (fd, ctlptr, dataptr, flags) 
int fd; 

struct strbuf *ctlptr; 
struct strbuf *dataptr; 
int *flags; 



The arguments to getmsg are the same as those for putmsg. 
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The Message Interface 



The remainder of this chapter presents an example that demonstrates how 
putmsg and getmsg may be used to interact with the service interface of a simple 
datagram protocol provider. A potential provider of such a service might be the 
IEEE 802.2 Logical Link Control Protocol Type 1. The example implements a 
user level library that would free the user from knowledge of the underlying 
STREAMS system calls. The Transport Interface of the Network Services 
Library in UNIX System Release 3.0 provides a similar function for transport 
layer services. The example here illustrates how a service interface might be 
defined, and is not an example of a complete IEEE 802.2 service interface. 



42 STREAMS PROGRAMMER'S GUIDE 




Datagram Service Interface Example 

The example datagram service interface library presented below includes four 
functions that enable a user to do the following: 

■ establish a Stream to the service provider and bind a protocol address to 
the Stream 

■ send a datagram to a remote user 

■ receive a datagram from a remote user 

■ close the Stream connected to the provider 

First, the structure and constant definitions required by the library are shown. 
These typically will reside in a header file associated with the service interface. 
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struct unitdata_req { /* 

long FRIM_type ; /* 

long DEST_addr ; /* 

}; 

struct ok_ack { /* 

long ERIMtype ; /* 

}; 

struct error ack { /* 

long PRIM_type ; /* 

long UNIX_error ; /* 

}; 

struct unitdata_ind { /* 

long PRIM type; /* 

long SRC addr; /* 

}; 

/* union of all primitives */ 
union primitives { 

long type; 

struct bind_req bindjreq; 

struct unitdata_req unitdata_req; 

struct ok_ack ok ack; 

struct error _ack error ack; 

struct unitdata ind unitdata ind; 

}; 

/* header files needed by library */ 
#include <stropts.h> 

#include <stdio.h> 

#include <ermo.h> 




unitdata request */ 
always UNITDATA_REQ */ 
destination addr */ 

positive acknowledgment */ 
always OK_ACK */ 

error acknowledgment */ 
always ERRGR_ACK */ 

UNIX error code */ 

unitdata indication */ 
always UNITDATA IND */ 
source addr */ 





Five primitives have been defined. The first two represent requests from the 
service user to the service provider. These are: 

BIND REQ This request asks the provider to bind a specified protocol 
address. It requires an acknowledgement from the provider 
to verify that the contents of the request were syntactically 
correct. 
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Datagram Service Interface Example 



UNITDATAREQ 

This request asks the provider to send a datagram to the 
specified destination address. It does not require an ack- 
nowledgement from the provider. 

The three other primitives represent acknowledgements of requests, or indica- 
tions of incoming events, and are passed from the service provider to the service 
user. These are: 

OKACK This primitive informs the user that a previous bind request 

was received successfully by the service provider. 

ERROR_ACK This primitive informs the user that a non-fatal error was 
found in the previous bind request. It indicates that no 
action was taken with the primitive that caused the error. 

UNITDATAIND 

This primitive indicates that a datagram destined for the 
user has arrived. 

The structures defined above describe the contents of the control part of each 
service interface message passed between the service user and service provider. 
The first field of each control part defines the type of primitive being passed. 



Accessing the Datagram Provider 

The first routine presented below, inter open, opens the protocol driver device 
file specified by path and binds the protocol address contained in addr so that it 
may receive datagrams. On success, the routine returns the file descriptor associ- 
ated with the open Stream; on failure, it returns -1 and sets errno to indicate the 
appropriate UNIX system error value. 
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After opening the protocol driver, inter open packages a bind request message 
to send downstream, putmsg is called to send the request to the service provider. 
The bind request message contains a control part that holds a bind_req structure, 
but it has no data part, ctlbuf is a structure of type strbuf, and it is initialized 
with the primitive type and address. Notice that the maxlen field of ctlbuf is not 
set before calling putmsg. That is because putmsg ignores this field. The dataptr 
argument to putmsg is set to NULL to indicate that the message contains no data 
part. Also, the flags argument is 0, which specifies that the message is not a 
priority message. 

After inter open sends the bind request, it must wait for an acknowledgement 
from the service provider, as follows: 
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getmsg is called to retrieve the acknowledgement of the bind request. The 
acknowledgement message consists of a control part that contains either an 
ok ack or error ack structure, and no data part. 

The acknowledgement primitives are defined as priority messages. Two 
classes of messages can arrive at the Stream head: priority and normal. Normal 
messages are queued in a first-in-first-out manner at the Stream head, while prior- 
ity messages are placed at the front of the Stream head queue. The STREAMS 
mechanism allows only one priority message per Stream at the Stream head at 
one time; any further priority messages are discarded until the first message is 
processed. Priority messages are particularly suitable for acknowledging service 
requests when the acknowledgement should be placed ahead of any other mes- 
sages at the Stream head. 



NOTE 



These messages are not intended to support the expedited data capabilities of 
many communication protocols, as evidenced by the one-at-a-time restriction just 
described. 



Before calling getmsg, this routine must initialize the strbuf structure for the 
control part, buf should point to a buffer large enough to hold the expected con- 
trol part, and maxlen must be set to indicate the maximum number of bytes this 
buffer can hold. 

Because neither acknowledgement primitive contains a data part, the dataptr 
argument to getmsg is set to NULL. The flags argument points to an integer 
containing the value RSHIPRI. This flag indicates that getmsg should wait for a 
STREAMS priority message before returning, and is set because the ack- 
nowledgement primitives are priority messages. Even if a normal message is 
available, getmsg will block until a priority message arrives. 

On return from getmsg, the len field is checked to ensure that the control part 
of the retrieved message is an appropriate size. The example then checks the 
primitive type and takes appropriate actions. An OK_ACK indicates a successful 
bind operation, and inter open returns the file descriptor of the open Stream. An 
ERRORACK indicates a bind failure, and err no is set to identify the problem 
with the request. 
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Closing the Service 

The next routine in the datagram service library is inter close, which closes 
the Stream to the service provider. 




The routine simply closes the given file descriptor. This will cause the proto- 
col driver to free any resources associated with that Stream. For example, the 
driver may unbind the protocol address that had previously been bound to that 
Stream, thereby freeing that address for use by some other service user. 



Sending a Datagram 

The third routine, inter snd, passes a datagram to the service provider for 
transmission to the user at the address specified in addr. The data to be transmit- 
ted is contained in the buffer pointed to by buf and contains len bytes. On suc- 
cessful completion, this routine returns the number of bytes of data passed to the 
service provider; on failure, it returns -1 and sets errno to an appropriate UNIX 
system error value. 
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In this example, the datagram request primitive is packaged with both a con- 
trol part and a data part. The control part contains a unitdatajeq structure that 
identifies the primitive type and the destination address of the datagram. The 
data to be transmitted is placed in the data part of the request message. 

Unlike the bind request, the datagram request primitive requires no ack- 
nowledgement from the service provider. In the example, this choice was made to 
minimize the overhead during data transfer. Since datagram services are 
inherently unreliable, this is a valid design choice. If the putmsg call succeeds, 
this routine assumes all is well and returns the number of bytes passed to the ser- 
vice provider. 
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Datagram Service Interface Example 



Receiving a Datagram 

The final routine in this example, inter _rcv, retrieves the next available 
datagram, buf points to a buffer where the data should be stored, len indicates 
the size of that buffer, and addr points to a long integer where the source address 
of the datagram will be placed. On successful completion, inter jcv returns the 
number of bytes in the retrieved datagram; on failure, it returns -1 and sets the 
appropriate UNIX system error value. 
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getmsg is called to retrieve the datagram indication primitive, where that 
primitive contains both a control and data part. The control part consists of a 
unitdatajnd structure that identifies the primitive type and the source address of 
the datagram sender. The data part contains the data itself. 

In ctlbuf \ buf must point to a buffer where the control information will be 
stored, and maxlen must be set to indicate the maximum size of that buffer. 
Similar initialization is done for databuf. 

The flags argument to getmsg is set to zero, indicating that the next message 
should be retrieved from the Stream head, regardless of its priority. Datagrams 
will arrive in normal priority messages. If no message currently exists at the 
Stream head, getmsg will block until a message arrives. 

The user’s control and data buffers should be large enough to hold any incom- 
ing datagram. If both buffers are large enough, getmsg will process the datagram 
indication and return 0, indicating that a full message was retrieved successfully. 
However, if either buffer is not large enough, getmsg will only retrieve the part of 
the message that fits into each user buffer. The remainder of the message is 
saved for subsequent retrieval, and a positive, non-zero value is returned to the 
user. A return value of MORECTL indicates that more control information is 
waiting for retrieval. A return value of MOREDATA indicates that more data is 
waiting for retrieval. A return value of MORECTL|MOREDATA indicates that 
data from both parts of the message remain. In the example, if the user buffers 
are not large enough (that is, getmsg returns a positive, non-zero value), the func- 
tion will set errno to EIO and fail. 

The type of the primitive returned by getmsg is checked to make sure it is a 
datagram indication. The source address is then set and the number of bytes of 
data in the datagram is returned. 

The above example presented a simplified service interface. The state transi- 
tion rules for such an interface were not presented for the sake of brevity. The 
intent was to show typical uses of the putmsg and getmsg system calls. See 
putmsg(2) and getmsg (2) for further details. 
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PART 2: MODULE AND DEVICE DRIVERS 



Introduction to Part 2 



Part 2 of this guide, Module and Driver Programming, describes the use of 
STREAMS kernel facilities for developing and installing modules and drivers. It 
is intended for system programmers with knowledge of UNIX system kernel pro- 
gramming, device driver development, and networking and other data communica- 
tion facilities. Knowledge of the STREAMS Primer and the Driver Design Guide 
is assumed. 

STREAMS provides module and driver developers with integral functions, a 
set of utility routines, and facilities that expedite design and implementation. The 
principle development facilities are listed below: 

■ Message storage management - to maintain STREAMS own memory 
resources for message storage 

■ Flow control - to conserve STREAMS memory and processing resources 

■ Scheduling - to control the execution of service procedures 

■ Multiplexing - to switch data among multiple Streams 

■ Error and trace loggers - for debugging and administrative use 



Part 2 is organized as follows: 

■ Chapter 5, Streams Mechanism, reviews the operation of STREAMS and 
describes how a Stream is constructed and dismantled. 

■ Chapter 6, Modules, describes the basic STREAMS data structures and 
the organization of a module. 

■ Chapter 7, Messages, introduces message blocks, read and write system 
calls, and the message storage pool. 

■ Chapter 8, Message Queues and Service Procedures, discusses put and ser- 
vice procedures, message queueing and basic flow control. 

■ Chapter 9, Drivers, describes STREAMS driver organization and discusses 
typical driver processing. 
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Introduction to Part 2 



■ Chapter 10, Complete Driver, provides a full implementation of a driver 
and describes the clone mechanism. 

■ Chapter 11, Multiplexing, describes the multiplexing facility. 

■ Chapter 12, Service Interface, discusses service interfaces within a Stream 
and at the Stream/user boundary. 

■ Chapter 13, Advanced Topics, contains advanced topics including signals 
and Stream head options. 

■ Appendix A, Kernel Structures, summarizes kernel structures used by 
modules and drivers. 

■ Appendix B, Message Types, describes STREAMS message types. 

■ Appendix C, Utilities, specifies the STREAMS kernel utility routines. 

■ Appendix D, Design Guidelines, summarizes module and driver design 
guidelines. 

■ Appendix E, Configuring, describes how modules and drivers are 
configured into the UNIX system, tunable parameters and STREAMS sys- 
tem error messages. 

■ The Glossary defines terms unique to STREAMS. 
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CHAPTER 5: STREAMS MECHANISM 



Overview 

A Stream implements a connection within the kernel between a driver in ker- 
nel space and a process in user space. It provides a general character 
input/output (I/O) interface for user processes which is upwardly compatible with 
the interface of the preexisting character I/O facilities. A Stream is analogous to 
a shell pipeline except that data flow and processing are bidirectional to support 
concurrent input and output. 

The components that form a Stream are the Stream head, driver and optional 
modules (see Figure 1 in the Preface) . A Stream is initially constructed as the 
result of a user process open (2) system call referencing a STREAMS file. The 
call causes a kernel resident driver to be connected with a Stream head to form a 
Stream. Subsequent ioctl(2) calls select kernel resident modules and cause them 
to be inserted in the Stream. A module represents intermediate processing on 
messages flowing between the Stream head and driver. A module can function as, 
for example, a communication protocol, line discipline or data filter. STREAMS 
allows a user to connect a module with any other module. The user determines 
the module connection sequences that result in useful configurations. 

A process can send and receive characters on a Stream using write (2) and 
read (2), as on character files. When user data enters the Stream head or external 
data enters the driver, the data is placed into messages for transmission on the 
Stream. All data passed on a Stream is carried in messages, each having a 
defined message type identifying the message contents. Internal control and 
status information is transmitted among modules or between the Stream and user 
process as messages of certain types interleaved on the Stream. Modules and 
drivers can send certain message types to the Stream head to cause the generation 
of signals or errors to be received by the user process. 

A module is comprised of two identical sets of data structures called 
QUEUEs. One QUEUE is for upstream processing and the other is for down- 
stream processing. The processing performed by the two QUEUEs is generally 
independent so that a Stream operates in a full-duplex manner. The interface 
between modules is uniform and simple. Messages flow from module to module. 

A message from one module is passed to the single entry point of its neighboring 
module. 
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Overview 



The last close (2) system call dismantles the Stream and closes the file, 
semantically identical to character I/O drivers. 

STREAMS supports implementation of user level applications with extensions 
to the above general system calls and STREAMS specific system calls: putmsg(2), 
getmsg(2), poll (2) and a set of STREAMS generic ioctl(2) functions. 
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Stream Construction 



STREAMS constructs a Stream as a linked list of kernel resident data struc- 
tures. In a STREAMS file, the inode points to the Stream header structure. The 
header is used by STREAMS kernel routines to perform operations on this 
Stream generally related to system calls. Figure 5-1 depicts the downstream 
(write) portion of a Stream (see Chapter 3 of the Primer) connected to the 
header. There is one header per Stream. From the header onward, a Stream is 
constructed of QUEUEs. The upstream (read) portion of the Stream (not shown 
in Figure 5-1) parallels the downstream portion in the opposite direction and ter- 
minates at the Stream header structure. 




Figure 5-1: Downstream Stream Construction 



At the same relative location in each QUEUE is the address of the entry 
point, a procedure to be executed on any message received by that QUEUE. The 
procedure for QUEUE H, at one end of the Stream, is the STREAMS provided 
Stream head routine. QUEUE H is the downstream half of the Stream head. 

The procedure for QUEUE D, at the other end, is the driver routine. QUEUE D 
is the downstream half of the Stream end. PI and P2 are pushable modules, each 
containing their own unique procedures. That is, all STREAMS components are 
of similar organization. 

This similarity results in the uniform manner of navigating in either direction 
on a Stream: messages move from one end to the other, from QUEUE to the next 
linked QUEUE, executing the procedure specified in the QUEUE. 

Figure 5-2 shows the data structures forming each QUEUE: queuet, qinit, 
moduleinfo and modulestat. queue t contains various modifiable values for this 
QUEUE, generally used by STREAMS, qinit contains a pointer to the processing 
procedures, module info contains limit values and module stat is used for statis- 
tics. The two QUEUEs in a module will generally each contain a different set of 
these structures. The contents of these structures are described in following 
chapters. 
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Stream Construction 




Figure 5-2: QUEUE Data Structures 



Figure 5-1 shows QUEUE linkage in one direction while Figure 5-2 shows 
two neighboring modules with links (solid vertical arrows) in both directions. 
When a module is pushed onto a Stream, STREAMS creates two QUEUES and 
links each QUEUE in the module to its neighboring QUEUE in the upstream and 
downstream direction. The linkage allows each QUEUE to locate its next neigh- 
bor. The next relation is implemented between queuets in adjacent modules by 
the qjiext pointer. Within a module, each queuet locates its mate (see dotted 
arrows in Figure 5-2) by use of STREAMS macros, since there is no pointer 
between the two queue ts. The existence of the Stream head and driver is known 
to the QUEUE procedures only as destinations towards which messages are sent. 
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Opening a Stream 



When a file is opened [see open(2)], a STREAMS file is recognized by a 
non-null value in the dstr field of the associated cdevsw entry, djtr points to a 
streamtab structure: 



struct streamtab { 



struct qinit 
struct qinit 
struct qinit 
struct qinit 



*st_rdinit; /* defines read QUEUE */ 

*st_wrinit; /* defines write QUEUE */ 
*st_rauxrinit; /* for multiplexing drivers only */ 
*st_muxwinit; /* for multiplexing drivers only */ 



streamtab defines a module or driver and points to the read and write qinit 
structures for the driver. 

If this open call is the initial file open, a Stream is created. First, the single 
header structure and the Stream head (see Figure 5-1) queue_t structure pair are 
allocated. Their contents are initialized with predetermined values including, as 
noted above (see QUEUE H), the Stream head processing routines. 

Then, a queuet structure pair is allocated for the driver. The queue_t con- 
tents are zero unless specifically initialized (see Chapter 8) . A single, common 
qinit structure pair is shared among all the Streams opened from the same cdevsw 
entry, as is the associated moduleinfo and modulestat structures (see Figure 5-2). 

Next, the qjiext values are set so that the Stream head write queue_t points 
to the driver write queue_t and the driver read queue t points to the Stream head 
read queue_t. The qjiext values at the ends of the Stream are set to NULL. 
Finally, the driver open procedure (located via qinit) is called. 

If this open is not the initial open of this Stream, the only actions performed 
are to call the driver open and the open procedures of all pushable modules on the 
Stream. 



STREAMS MECHANISM 59 




Adding and Removing Modules 



As part of constructing a Stream, a module can be added with an ioctl 
I_PUSH [see streamio(7)] system call (push). The push inserts a module beneath 
the Stream head. Because of the similarity of STREAMS components, the push 
operation is similar to the driver open. First, the address of the qinlt structure for 
the module is obtained via an fmodsw entry. 

fmodsw is an array, analogous to cdevsw. Each fmodsw entry corresponds to 
a unique module and contains the name of the module (used by I PUSH and cer- 
tain other STREAMS ioctls) and a pointer to the module’s streamtab. Next, 
STREAMS allocates queue _t structures and initializes their contents as in the 
driver open, above. As with the driver, the read and write qinit structures are 
shared among all the modules opened from this fmodsw entry (see Figure 5-2). 

Then, qjiext values are set and modified so that the module is interposed 
between the Stream head and the driver or module previously connected to the 
head. Finally, the module open procedure (located via qinit) is called. Unlike 
open, no other module or driver open procedure is called. 

Each push of a module is independent, even in the same Stream. If the same 
module is pushed more than once onto a Stream, there will be multiple 
occurrences of that module in the Stream. The total number of pushable modules 
that may be contained on any one Stream is limited by the kernel parameter 
NSTRPUSH (see Appendix E). 

An ioctl I_POP [see streamio(7)] system call (pop) removes the module 
immediately below the Stream head. The pop calls the module close procedure. 
On return from the module close, any messages left on the module’s message 
queues are freed (deallocated) . Then, STREAMS connects the Stream head to 
the component previously below the popped module and deallocates the module’s 
two queue_t structures. I POP enables a user process to dynamically alter the 
configuration of a Stream by pushing and popping modules as required. For 
example, a module may be removed or a new one inserted below a module. In the 
latter case, the original module is popped and pushed back after the new module 
has been pushed. 

An I POP cannot be used on a driver. 
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Closing 



The last close system call to a STREAMS file dismantles the Stream. Dis- 
mantling consists of popping any modules on the Stream, closing the driver and 
closing the file. Before a module is popped by close, it may delay to allow any 
messages on the write message queue of the module to be drained by module pro- 
cessing. If ONDELAY [see open (2)] is clear, close will wait up to 15 seconds 
for each module to drain. If 0_NDELAY is set, the pop is performed immedi- 
ately. close will also wait for the driver’s write queue to drain. Messages can 
remain queued, for example, if flow control (see Chapter 6 in the Primer ) is inhi- 
biting execution of the write QUEUE. When all modules are popped and any 
wait for the driver to drain is completed, the driver close routine is called. On 
return from the driver close, any messages left on the driver’s message queues are 
freed, and the queue t and header structures are deallocated. 



NOTE 



STREAMS frees only the messages contained on a message queue. Any mes- 
sages used internally by the driver or module must be freed by the driver or 
module close procedure. 



Finally, the file is closed. 
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CHAPTER 6: MODULES 



Module Declarations 

A module and driver will contain, as a minimum, declarations of the following 
form: 




The contents of these declarations are constructed for the null module exam- 
ple in this section. This module performs no processing: Its only purpose is to 
show linkage of a module into the system. The descriptions in this section are 
general to all STREAMS modules and drivers unless they specifically reference 
the example. 

The declarations shown are: the header set; the read and write QUEUE 
( rminfo and wminfo) moduleinfo structures (see Figure 5-2); the module open, 
read-put, write-put and close procedures; the read and write (rinit and winit) qinit 
structures; and the streamtab structure. 



62 STREAMS PROGRAMMER S GUIDE 




Module Declarations 



The minimum header set for modules and drivers is types.h and stream.h. 
param.h contains definitions for NULL and other values for STREAMS modules 
and drivers as shown in the section titled "Accessible Symbols and Functions" in 
Appendix D. 



NOTE 



Configuring a STREAMS module or driver (see Appendix E) does not require 
any procedures to be externally accessible, only streamtab. The streamtab struc- 
ture name must be the prefix used in configuring, appended with "info". 



As described in the previous chapter, streamtab contains qinit values for the read 
and write QUEUES, pointing to a moduleinfo and an optional modulestat struc- 
ture. The two required structures, shown in Figure 5-2, are these: 

struct qinit { 



int 


(*qi_putp) ( ); 


/* put procedure */ 




int 


(*qi_srvp) ( ); 


/* service procedure */ 




int 


(*qi_qopen) ( ); 


/* called an each open or a push */ 


int 


( *qi_qclose ) ( ); 


/* called an last close or 


a pop */ 


int 


(•»Kii_qadmin) ( ); 


/* reserved for future use 


*/ 



struct modu!e_info *qi minfo; /* information structure */ 

struct module _s tat *qi ms tat; /* statistics structure - optional */ 

}; 



struct nodule info { 



ushort 


mi idnum; 


char 


*mi idname 


short 


mi minpsz; 


short 


mi maxpsz; 


short 


mi hiwat; 


ushort 


mi lowat; 



/* module ID number */ 

/* module name */ 

/* min packet size accepted, for developer use */ 
/* max packet size accepted, for developer use */ 
/* hi -water mark, for flow control */ 

/* lo-water mark, for flow control */ 



qinit contains the QUEUE procedures. All modules and drivers with the 
same streamtab (i.e., the same fmodsw or cdevsw entry) point to the same 
upstream and downstream qinit structure (s). The structure is meant to be 
software read-only, as any changes to it affect all instantiations of that module in 
all Streams. Pointers to the open and close procedures must be contained in the 
read qinit. These fields are ignored in the write side. The example has no service 
procedure on the read or write side. 

moduleinfo contains identification and limit values. All modules and drivers 
with the same streamtab point to the same upstream and downstream module info 
structure (s). As with qinit, this structure is intended to be software read-only. 
However, the four limit values are copied to queue_t (see Chapter 8) where they 
are modifiable. In the example, the flow control high and low water marks (see 
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Module Declarations 

Chapter 9) are zero since there are no service procedures and messages are not 
queued in the module. 

Three names are associated with a module: the character string in fmodsw, 
obtained from the name of the master.d file used to configure the module (see 
Appendix E); the prefix for streamtab, used in configuring the module; and the 
module name field in the module_info structure. This field is a hook for future 
expansion and is not currently used. However, it is recommended that it be the 
same as the master.d file name. The module name value used in the I_PUSH or 
other STREAMS ioctl commands is contained in fmodsw. Each module ID and 
module name should be unique in the system. The module ID is currently used 
only in logging and tracing (see Chapter 6 in the Primer ) . For the example in 
this chapter, the module ID is zero. 

Minimum and maximum packet size are intended to limit the total number of 
characters contained in all (if any) of the M DATA blocks in each message 
passed to this QUEUE. These limits are advisory except for the Stream head. 

For certain system calls that write to a Stream, the Stream head will observe the 
packet sizes set in the write QUEUE of the module immediately below it. Other- 
wise, the use of packet size is developer dependent. In the example, INFPSZ 
indicates unlimited size on the read (input) side. 

module_stat is optional, intended for future use. Currently, there is no 
STREAMS support for statistical information gathering. The structure is 
described in Appendix A. 
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Module Procedures 

The null module procedures are as follows: 




The form and arguments of these four procedures are the same in all modules 
and all drivers. Modules and drivers can be used in multiple Streams and their 
procedures must be reentrant. 
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Module Procedures 



modopen illustrates the open call arguments and return value. The argu- 
ments are the read queue pointer (< q ), the major/minor device number (dev, in 
drivers only), the file open flags (flag, defined in sys/file.h), and the Stream open 
flag (sflag). For a module, the value of flag and dev are always zero. The 
Stream open flag can take on the following values: 

MODOPEN normal module open 

0 normal driver open (see Chapter 9) 

CLONEOPEN clone driver open (see Chapter 10) 

The return value from open is > = 0 for success and OPENFAIL for error. 
The open procedure is called on the first IPUSH and on all subsequent open calls 
to the same Stream. During a push, a return value of OPENFAIL causes the 
I PUSH to fail and the module to be removed from the Stream. If OPENFAIL 
is returned by a module during an open call, the open fails, but the Stream 
remains intact. For example, it can be returned by a module/driver that only 
wishes to be opened by a superuser: 

if ( !suser( )) return OPENFAIL; 

In the example, modopen simply returns successfully, modrput and modwput 
illustrate the common interface to put procedures. The arguments are the read or 
write queuet pointer, as appropriate, and the message pointer. The put procedure 
in the appropriate side of the QUEUE is called when a message is passed from 
upstream or downstream. The put procedure has no return value. In the exam- 
ple, no message processing is performed. All messages are forwarded using the 
putnext macro (see Appendix C) . putnext calls the put procedure of the next 
QUEUE in the proper direction. 

The close procedure is only called on an I_POP or on the last close call of the 
Stream (see the last two sections of Chapter 5) . The arguments are the read 
queue t pointer and the file open flags as in modopen. For a module, the value of 
flag is always zero. There is no return value. In the example, modclose does 
nothing. 
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Module and Driver Environment 



As discussed in Chapter 7 of the Primer , user context is not generally avail- 
able to STREAMS module procedures and drivers. The exception is during exe- 
cution of the open and close routines. Driver and module open and close routines 
have user context and may access the uarea structure (defined in user.h, see 
"Accessible Symbols and Functions" in Appendix D) . These routines are allowed 
to sleep, but must always return to the caller. That is, if they sleep, it must be at 
priority <= PZERO, or with PCATCH set in the sleep priority. (A process 
which is sleeping at priority > PZERO and is sent a signal via kill (2), never 
returns from the sleep call. Instead, the system call is aborted.) 

V STREAMS driver and module put procedures and service procedures have no 

user context. They cannot access the u area structure of a process and must not 
sleep. 
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CHAPTER 7: MESSAGES 



Message Format 

Messages are the means of communication within a Stream. A message con- 
tains data or information identified by one of 18 message types (see Appendix B). 
Messages may be generated by a driver, a module, or the Stream head. The con- 
tents of certain message types can be transferred between a process and a Stream 
by use of system calls. STREAMS maintains its own pools for allocation of mes- 
sage storage. 

All messages are composed of one or more message blocks. A message block 
is a linked triplet, two structures and a variable length buffer block. The struc- 
tures are msgb (mblkt), the message block, and datab (dblkt), the data block: 

struct msgb { 
struct 
struct 
struct 
unsigned 
unsigned 
struct 

}; 

typedef struct 



struct datab { 
struct 


datab 


*db freep;/* used internally */ 


unsigned 


char 


*db_base ; /* first byte of buffer * */ 


unsigned 


char 


*db lim;/* last byte+1 of buffer */ 


unsigned 


char 


db_ref ; /* count of messages pointing to this block */ 


unsigned 


char 


db_type ; /* message type */ 


unsigned 

i . 


char 


db class;/* used internally */ 


/ > 

typedef struct 


datab dblk t; 



msgb *b_next;/* next message on queue */ 

msgb *b prev;/* previous message an queue */ 

msgb *b_cant;/* next message block of message */ 

char *b rptr;/* first unread byte in buffer */ 

char *b_wptr;/* first unwritten byte in buffer */ 

datab *b_datap;/* data block */ 

msgb iriblk t; 



mblkt is used to link messages on a message queue, link the blocks in a mes- 
sage and manage the reading and writing of the associated buffer, b rptr and 
b_wptr are used to locate the data currently contained in the buffer. As shown in 
Figure 7-1, mblk t points to the data block of the triplet. The data block contains 
the message type, buffer limits and control variables. STREAMS allocates mes- 
sage buffer blocks of varying sizes (see below) . db base and dbjim are the fixed 
beginning and end (+1) of the buffer. 
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Message Format 



A message consists of one or more linked message blocks. Multiple message 
blocks in a message can occur, for example, because of buffer size limitations, or 
as the result of processing that expands the message. When a message is com- 
posed of multiple message blocks, the type associated with the first message block 
determines the message type, regardless of the types of the attached message 
blocks. 




Figure 7-1: Message Form and Linkage 
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Message Format 



A message may occur singly, as when it is processed by a put procedure, or it 
may be linked on the message queue in a QUEUE, generally waiting to be pro- 
cessed by the service procedure. Message 1, as shown in Figure 7-1, links to mes- 
sage 2. In the first message on a queue, b _prev points back to the header in the 
QUEUE. The last bjiext points to the tail. 

Note that a data block in message 1 is shared between message 1 and another 
message. Multiple message blocks can point to the same data block to conserve 
storage and to avoid copying overhead. For example, the same data block, with 
associated buffer, may be referenced in two messages, from separate modules that 
implement separate protocol levels. (Figure 7-1 illustrates the concept, but data 
blocks would not typically be shared by messages on the same queue). The buffer 
can be retransmitted, if required by errors or timeouts, from either protocol level 
without replicating the data. Data block sharing is accomplished by means of a 
utility routine (see dupmsg in Appendix C) . STREAMS maintains a count of the 
message blocks sharing a data block in the dbjef field. 

STREAMS provides utility routines and macros, specified in Appendix C, to 
assist in managing messages and message queues, and to assist in other areas of 
module and driver development. A utility should always be used when operating 
on a message queue or accessing the message storage pool. 



Message Generation and Reception 

As discussed in the "Message Types" section in Chapter 4 of the Primer , most 
message types can be generated by modules and drivers. A few are reserved for 
the Stream head. The most commonly used types are M_DATA, M_PROTO and 
M_PCPROTO. These, and certain other message types, can also be passed 
between a process and the topmost module in a Stream, with the same message 
boundary alignment maintained on both sides of the kernel. This allows a user 
process to function, to some degree, as a module above the Stream and maintain a 
service interface (see Chapter 12). MPROTO and MPCPROTO messages are 
intended to carry service interface information among modules, drivers and user 
processes. Some message types can only be used within a Stream and cannot be 
sent or received from user level. 

As discussed previously, modules and drivers do not interact directly with any 
system calls except open and close. The Stream head handles all message transla- 
tion and passing. Message transfer between process and Stream head can occur 
in different forms. For example, M DATA, M PROTO or M PCPROTO mes- 
sages can be transferred in their direct form by getmsg(2) and putmsg(2) system 
calls (see Chapter 12). Alternatively, a write causes one or more M_DATA 
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Message Format 



messages to be created from the data buffer supplied in the call. M_DATA mes- 
sages received from downstream at the Stream head will be consumed by read (2) 
and copied into the user buffer. As another example, M SIG causes the Stream 
head to send a signal to a process (see Chapter 13). 

Any module or driver can send any message type in either direction on a 
Stream. However, based on their intended use in STREAMS and their treatment 
by the Stream head, certain message types can be categorized as upstream, down- 
stream or bidirectional. M DATA, M PROTO or M PCPROTO messages, for 
example, can be sent in both directions. Other message types are intended to be 
sent upstream to be processed only by the Stream head. Downstream messages 
are silently discarded if received by the Stream head. 
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Filter Module Declarations 



The module shown below, crmod , is an asymmetric filter. On the write side, 
newline is converted to carriage return followed by newline. On the read side, no 
conversion is done. The declarations are essentially the same as the null module 
of the preceding chapter: 




Note that, in contrast to the null module example, a single moduleinfo struc- 
ture is shared by the read and write sides. A master.d file to configure crmod is 
shown in Appendix E. 

modopen , modrput and modclose are the same as in the null module of the 
preceding chapter. 
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Filter Module Declarations 



bappend Subroutine 

The module makes use of a subroutine, bappend , which appends a character 
to a message block: 




bappend receives a pointer to a message block pointer and a character as 
arguments. If a message block is supplied ( *bpp ! = NULL ) , bappend checks if 
there is room for more data in the block. If not, it fails. If there is no message 
block, a block of at least MODBLKSZ is allocated through allocb, described 
below. 
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Filter Module Declarations 



If the allocb fails, bappend returns success, silently discarding the character. 
This may or may not be acceptable. For TTY-type devices, it is generally 
accepted. If the original message block is not full or the allocb is successful, bap- 
pend stores the character in the block. 
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Message Allocation 

The allocb utility (see Appendix C) is used to allocate message storage from 
the STREAMS pool. Its declaration is: 

mblk t *allocb(buffersize, priority). 

allocb will return a message block containing a buffer of at least the size 
requested, providing there is a buffer available at the message pool priority 
specified, or it will return NULL on failure. Three levels of message pool priority 
can be specified (see Appendix C) . Priority generally does not affect allocb until 
the pool approaches depletion. In this case, for the same internal level of pool 
resources, allocb will fail low priority requests while granting higher priority 
requests. This allows module and driver developers to use STREAMS memory 
resources to their best advantage and for the common good of the system. Mes- 
sage pool priority does not affect subsequent handling of the message by 
STREAMS. BPRI HI is intended for special situations. This transmission of 
urgent messages relating to time sensitive events, conditions that could result in 
loss of state, loss of data or inability to recover. BPRI MED might be used, for 
example, when requesting an MDATA buffer for holding input, and BPRIJLO 
might be used for an output buffer (presuming the output data can wait in user 
space) . The Stream head uses BPRIJLO to allocate messages to contain output 
from a process (e.g., by write or putmsg). Note that allocb will always return a 
message of type M DATA. The type may then be changed if required, b rptr 
and bwptr are set to db base (see mblk t and dblk t) . 

allocb may return a buffer larger than the size requested. In bappend , if the 
message block contents were intended to be limited to MODBLKSZ, a check 
would have to be inserted. 

If allocb indicates buffers are not available, the bufcall utility can be used to 
defer processing in the module or the driver until a buffer becomes available (buf- 
call is described in Chapter 13). 
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Put Procedure 



modwput processes all the message blocks in any downstream data (type 
M DATA) messages. 



/* Write side put procedure */ 
static modwput (q, mp) 
queuejt *q; 
mblk_t *mp; 

{ 

switch (np->b_datap->db_type ) { 
default: 

putnext(q, mp) ; /* Don't do these, pass them along */ 

break; 

case M_DATA: { 

register mblk_t *bp; 

struct mblk_t *nmp = NULL, *nbp = NULL; 

for (bp = mp; bp 1= NULL; bp = bp->b_cont) { 
while (bp->b_rptr < bp->b_wptr) { 
if ( *bp->b rptr == '\n' ) 

if ( !bappend(&nbp, '\r')) 
goto newblk; 

if ( !bappend(&nbp, *bp->b_rptr ) ) 
goto newblk; 

bp->b_rptr++ ; 
continue; 

newblk: 

if (nrtp == NULL) 
nmp = nbp; 

else linkb(nmp, nbp) ; /* link message block to tail of nmp */ 
nbp = NULL; 

} 



if (nmp == NULL) 
nmp = nbp; 

else lihkb(nmp, nbp) ; 

freemsg(mp) ; /* de-allocate message */ 
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Put Procedure 




Data messages are scanned and filtered, modwput copies the original mes- 
sage into a new block (s), modifying as it copies, nbp points to the current new 
message block, nmp points to the new message being formed as multiple 
M_DATA message blocks. The outer forO loop goes through each message block 
of the original message. The inner while 0 loop goes through each byte, bappend 
is used to add characters to the current or new block. If bappend fails, the 
current new block is full. If nmp is NULL, nmp is pointed at the new block. If 
nmp is non-NULL, the new block is linked to the end of nmp by use of the linkb 
utility. 

At the end of the loops, the final new block is linked to nmp. The original 
message (all message blocks) is returned to the pool by freemsg. If a new mes- 
sage exists, it is sent downstream. 
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CHAPTER 8: MESSAGE QUEUES AND SERVICE 
PROCEDURES 



The queue_t Structure 

Service procedures, message queues and priority, and basic flow control are 
all intertwined in STREAMS. A QUEUE will generally not use its message 
queue if there is no service procedure in the QUEUE. The function of a service 
procedure is to process messages on its queue. Message priority and flow control 
are associated with message queues. 

The operation of a QUEUE revolves around the queue_t structure: 

struct queue { 

struct qinit *q_qinfo; /* 
struct msgb *q_first; /* 
struct msgb *q_last; /* 

struct queue *q_next; /* 

struct queue *q_link; /* 

caddrjt qjptr; /* 

ushort q_ count; /* 

ushort q_flag; /* 

short q_minpsz ; /* 

short q_maxpsz ; /* 

ushort q_h±wat ; /* 

ushort q_lowat; /* 

}; 

typedef struct queue queue_t; 

As described previously, two of these structures form a module. When a 
queue_t pair is allocated, their contents are zero unless specifically initialized. 

The following fields are initialized by STREAMS: 

■ q_qinfo - from streamtab 

■ qjninpsz , qjnaxpsz , qjiiwat , qjowat - from module_info 

Copying values from modulejnfo allows them to be changed in the queue t 
without modifying the template (i.e., streamtab and modulejnfo) values. 

q count is used in flow control calculations and is the weighted sum of the 
sizes of the buffer blocks currently on the message queue. The actual number of 
bytes in the buffer is not used. This is done to encourage the use of the smallest 
buffer that will hold the data intended to be placed in the buffer. 



procedures and limits for queue */ 
head of message queue for this QUEUE */ 
tail of message queue for this QUEUE */ 
next QUEUE in Stream*/ 

link to next QUEUE an STREAMS scheduling queue */ 
to private data structure */ 

weighted count of characters on message queue */ 
QUEUE state */ 

min packet size accepted by this QUEUE */ 
max packet size accepted by this QUEUE */ 
message queue high water mark, for flow control */ 
message queue low water mark, for flow control */ 
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Service Procedures 



Put procedures are generally required in pushable modules. Service pro- 
cedures are optional. The general processing flow when both procedures are 
present is as follows: A message is received by the put procedure in a QUEUE, 
where some processing may be performed on the message. The put procedure 
transfers the message to the service procedure by use of the putq utility, putq 
places the message on the tail (see q last in queuet) of the message queue. 

Then, putq will generally schedule (using q jink in queue t) the QUEUE for exe- 
cution by the STREAMS scheduler following all other QUEUES currently 
scheduled. After some indeterminate delay (intended to be short), the scheduler 
calls the service procedure. The service procedure gets the first message ( qjirst ) 
from the message queue with the getq utility. The service procedure processes the 
message and passes it to the put procedure of the next QUEUE with putnext. 

The service procedure gets the next message and processes it. This FIFO process- 
ing continues until the queue is empty or flow control blocks further processing. 
The service procedure returns to caller. 

V A service routine must never sleep and it has no user context. It must always 
return to its caller. 



If no processing is required in the put procedure, the procedure does not have 
to be explicitly declared. Rather, putq can be placed in the qinit structure 
declaration for the appropriate QUEUE side, to queue the message for the service 
procedure, e.g.: 

static struct qinit winit = { putq, modwsrv, }; 

More typically, put procedures will, as a minimum, process priority messages (see 
below) to avoid queueing them. 

The key attribute of a service procedure in the STREAMS architecture is 
delayed processing. When a service procedure is used in a module, the module 
developer is implying that there are other, more time-sensitive activities to be per- 
formed elsewhere in this Stream, in other Streams, or in the system in general. 
The presence of a service procedure is mandatory if the flow control mechanism is 
to be utilized by the QUEUE. 
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Service Procedures 



The delay for STREAMS to call a service procedure will vary with 
implementation and system activity. However, once the service procedure is 
scheduled, it is guaranteed to be called before user level activity is resumed. 

Also see the section titled Tut and Service Procedures" in Chapter 5 of the 
Primer. 
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Message Queues and Message Priority 



Figure 7-1 depicts a message queue linked by bjiext and b _prev pointers. As 
discussed in the Primer , message queues grow when the STREAMS scheduler is 
delayed from calling a service procedure because of system activity, or when the 
procedure is blocked by flow control. When it is called by the scheduler, the ser- 
vice procedure processes enqueued messages in FIFO order. However, certain 
conditions require that the associated message (e.g., an MERROR) reach its 
Stream destination as rapidly as possible. STREAMS does this by assigning all 
message types to one of the two levels of message queueing priority— priority and 
ordinary. As shown in Figure 8-1, when a message is queued, the putq utility will 
place priority messages at the head of the message queue, FIFO within their order 
of queueing. 




Head 



Tail 



Figure 8-1: Message Queue Priority 



Priority messages are not subject to flow control. When they are queued by 
putq, the associated QUEUE is always scheduled (in the same manner as any 
QUEUE; following all other QUEUEs currently scheduled) . When the service 
procedure is called by the scheduler, the procedure uses getq to retrieve the first 
message on queue, which will be a priority message, if present. Service pro- 
cedures must be implemented to act on priority messages immediately (see next 
section). The above mechanisms— priority message queueing, absence of flow 
control and immediate processing by a procedure— result in rapid transport of 
priority messages between the originating and destination components in the 
Stream. 
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Message Queues and Message Priority 



The priority level for each message type is shown in Appendix B. Message 
queue management utilities are provided for use in service procedures (see Appen- 
dix C) . 
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Flow Control 



The elements of flow control are discussed in Chapter 6 of the Primer. Flow 
control is only used in a service procedure. Module and driver coding should 
observe the following guidelines for message priority. Priority messages, deter- 
mined by the type of the first block in the message, 

(bp->b_datap->db_type > QPCTL ) , 

are not subject to flow control. They should be processed immediately and for- 
warded, as appropriate. 

For ordinary messages, flow control must be tested before any processing is 
performed. The canput utility determines if the forward path from the QUEUE 
is blocked by flow control. The manner in which STREAMS determines flow 
control status for modules and drivers is described under "Driver Flow Control" in 
Chapter 9. 

This is the general processing for flow control: Retrieve the message at the 
head of the queue with getq. Determine if the type is priority and not to be pro- 
cessed here. If both are true, pass the message to the put procedure of the follow- 
ing QUEUE with putnext. If the type is ordinary, use canput to determine if 
messages can be sent onward. If canput indicates messages should not be for- 
warded, put the message back on the queue with putbq and return from the pro- 
cedure. In all other cases, process the message. 

The canonical representation of this processing within a service procedure is 
as follows: 
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Flow Control 



NOTE 



A service procedure must process all messages on its queue unless flow control 
prevents this. 



When an ordinary message is enqueued by putq, putq will cause the service 
procedure to be scheduled only if the queue was previously empty. If there are 
messages on the queue, putq presumes the service procedure is blocked by flow 
control and the procedure will be automatically rescheduled by STREAMS when 
the block is removed. If the service procedure cannot complete processing as a 
result of conditions other than flow control (e.g., no buffers), it must assure it will 
return later (e.g., by use of bufcall, see Chapter 13) or it must discard all mes- 
sages on queue. If this is not done, STREAMS will never schedule the service 
procedure to be run unless the QUEUE’S put procedure queues a priority message 
with putq. 

putbq replaces messages at the beginning of the appropriate section of the 
message queue in accordance with their message type priority (see Figure 8-1). 
This might not be the same position at which the message was retrieved by the 
preceding getq. A subsequent getq might return a different message. 
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Example 



The filter module example of Chapter 7 is modified to have a service pro- 
cedure, as shown below. The declarations from the example in Chapter 7 are 
unchanged except for the following lines (changes are shown in bold) : 




stropts.h is generally intended for user level. However, it includes definitions 
of flush message options common to user level, modules and drivers, moduleinfo 
now includes the flow control high- and low-water marks (512 and 128) for the 
write QUEUE (even though the same module_info is used on the read QUEUE 
side, the read side has no service procedure so flow control is not used) . qinit now 
contains the service procedure pointer, modopen , modclose and modrput (read 
side put procedure) are unchanged from Chapters 6 and 7. The bappend subrou- 
tine is also unchanged from Chapter 7. 



Procedures 

The write side put procedures and the beginning of the service procedure are 
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Example 



shown below: 




ps crmod performs a similar function to crmod of the previous chapter, but it 
uses a service routine. 
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Example 



modwput , the write put procedure, switches on the message type. Priority 
messages that are not type M_FLUSH are putnext to avoid scheduling. The oth- 
ers are queued for the service procedure. An M FLUSH message is a request to 
remove all messages on one or both QUEUEs. It can be processed in the put or 
service procedure. 

modwsrv is the write service procedure. It takes a single argument, a pointer 
to the write queue_t. modwsrv processes only one priority message, M_FLUSH. 
All other priority messages are passed through. Actually, no other priority mes- 
sages should reach modwsrv. The check is included to show the canonical form 
when priority messages are queued by the put procedure. 

For an M_FLUSH message, modwsrv checks the first data byte. If 
FLUSHW (defined in stropts.h) is set in the byte, the write queue is flushed by 
use of fiushq. flushq takes two arguments, the queue pointer and a flag. The flag 
indicates what should be flushed, data messages (FLUSHDATA) or everything 
(FLUSHALL). In this case, data includes M DATA, M PROTO, and 
M_PCPROTO messages. The choice of what types of messages to flush is module 
specific. As a general rule, FLUSHDATA should be used. 

Ordinary messages will be returned to the queue if 
canput(q->q next) 

returns false, indicating the downstream path is blocked. 

In the remaining part of modwsrv , M_DATA messages are processed simi- 
larly to the previous example: 
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Example 
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Example 



The differences in M DATA processing between this and the previous exam- 
ple relate to the manner in which the new messages are forwarded and flow con- 
trol. For the purpose of demonstrating alternative means of processing messages, 
this version creates individual new messages rather than a single message contain- 
ing multiple message blocks. When a new message block is full, it is immediately 
forwarded with putnext rather than being linked into a single, large message (as 
was done in the previous example) . This alternative may not be desirable because 
message boundaries will be altered and because of the additional overhead of han- 
dling and scheduling multiple messages. 

When the filter processing is performed (following push), flow control is 
checked (canput) after, rather than before, each new message is forwarded. This 
is done because there is no provision to hold the new message until the QUEUE 
becomes unblocked. If the downstream path is blocked, the remaining part of the 
original message is returned to the queue. Otherwise, processing continues. 

Another difference between the two examples is that each message block of 
the original message is returned to the pool with freeb when its processing is 
completed. 
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CHAPTER 9: DRIVERS 



Overview of Drivers 

This chapter describes the organization of a STREAMS driver, and discusses 
some of the processing typically required in drivers. Certain elements of driver 
flow control are discussed. Procedures for handling user ioctls, common to 
modules and drivers, are described. 

As discussed under "Stream Construction" in Chapter 5, driver and module 
organization are very similar. The call interfaces to all the driver procedures are 
identical to module interfaces and driver procedures must be reentrant. As 
described under "Environment" in Chapter 6, the driver put and service pro- 
cedures have no user environment and cannot sleep. Other than with open and 
close, a driver interfaces with a user process by messages, and indirectly, through 
flow control. 

There are two significant differences between modules and drivers. First, a 
device driver must also be accessible from an interrupt as well as from the 
Stream, and second, a driver can have multiple Streams connected to it. Multiple 
connections occur when more than one minor device uses the same driver and in 
the case of multiplexors (see Chapter 11). However, these particular differences 
are not recognized by the STREAMS mechanism: They are handled by 
developer-provided code included in the driver procedures. 

Figure 9-1 shows multiple Streams (corresponding to minor devices), to a 
common driver. This depiction of two Streams connected to a single driver (also 
used in the Primer ) is somewhat misleading. These are really two distinct 
Streams opened from the same cdevsw (i.e., same major device). Consequently, 
they have the same streamtab and the same driver procedures. Modules opened 
from the same fmodsw might be depicted similarly if they had any reason to be 
cognizant, as do drivers, of common resources or alternate instantiations. 

Multiple instantiations (minor devices) of the same driver are handled during 
the initial open for each device. Typically, the queue t address is stored in a 
driver-private structure indexed by the minor device number. The structure is 
typically pointed at by q_ptr (see Chapter 8). When the messages are received by 
the QUEUE, the calls to the driver put and service procedures pass the address of 
the queue_t, allowing the procedures to determine the associated device. 
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Overview of Drivers 



In addition to these differences, a driver is always at the end of a Stream. As 
a result, drivers must include standard processing for certain message types that a 
module might simply be able to pass to the next component. 




0 1 
Figure 9-1: Device Driver Streams 
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Driver Flow Control 



The same utilities (described in Chapter 8), and mechanisms used for module 
flow control are used by drivers. However, they are typically used in a different 
manner in drivers, because a driver generally does not have a service procedure. 
The developer sets flow control values ( mijiiwat and milowat ) in the write side 
module info structure, which STREAMS will copy into qjiiwat and qjowat in 
the queuet structure of the QUEUE. A device driver typically has no write ser- 
vice procedure, but does maintain a write message queue. When a message is 
passed to the driver write side put procedure, the procedure will determine if 
device output is in progress. In the event output is busy, the put procedure cannot 
immediately send the message and calls the putq utility (see Appendix C) to 
queue the message. (Note that the driver might have elected to queue the mes- 
sage in all cases.) putq recognizes the absence of a service procedure and does not 
schedule the QUEUE. 

When the message is queued, putq increments the value of q_count (approxi- 
mately the enqueued character count, see the beginning of Chapter 8) by the size 
of the message and compares the result against the driver’s write high water limit 
( qjiiwat ) value. If the count exceeds qjiiwat , putq will set the internal FULL 
(see the section titled "Flow Control" in Chapter 6 of the Primer) indicator for 
the driver write QUEUE. This will cause messages from upstream to be halted 
(canput returns FALSE) until the write queue count reaches qjowat . The driver 
messages waiting to be output are dequeued by the driver output interrupt routine 
with getq, which decrements the count. If the resulting count is below qjowat , 
getq will back-enable any upstream QUEUE that had been blocked. The above 
STREAMS processing also applies to modules on both write and read sides of the 
Stream. 

Device drivers typically discard input when unable to send it to a user pro- 
cess. However, STREAMS allows flow control to be used on the driver read side, 
possibly to handle temporary upstream blocks. This is described in Chapter 13 in 
the section titled "Advanced Flow Control". 

To some extent, a driver or module can control when its upstream transmis- 
sion will become blocked. Control is available through the M SETOPTS message 
(see Chapter 1 3 and Appendix B) to modify the Stream head read side flow con- 
trol limits. 
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Driver Programming 



The example below shows how a simple interrupt-per-character line printer 
driver could be written. The driver is unidirectional and has no read side process- 
ing. It demonstrates some differences between module and driver programming, 
including the following: 

Open handling A driver is passed a minor device number or is asked to 
select one (see next chapter) . 

Flush handling A driver must loop M_FLUSH messages back upstream. 

Ioctl handling A driver must nak ioctl messages it does not understand. 

This is discussed under "Driver and Module Ioctls", below. 

Write side flow control is also illustrated as described above. 



Driver Declarations 

The driver declarations are as follows: 
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Driver Programming 



continued 



static int lpopen( ), lpclose( ), lpwput( ); 

static struct qinit rinit = { 

NULL, NULL, lpopen, lpclose, NULL, &minfo, NULL 

}; 

static struct qinit winit = { 

lpwput, NULL, NULL, NULL, NULL, &minfo, NULL 

}; 

struct streamtab lpinfo = { &rinit, &winit, NULL, NULL }; 



^define SET OPTIONS (('l'«8) ! 1 )/* really must be in a .h file */ 
/* 

* This is a private data structure, one per minor device number. 

*/ 

struct lp { 

short flags; /* flags — see below */ 
mblk_t *msg; /* current message being output */ 
queue t *qptr; /* back pointer to write queue */ 

}; 

/* Flags bits */ 

^define BUSY 1 * device is running and interrupt is pending */ 



extern struct lp lp_lp[ ] ; /* per device lp structure array */ 
extern int lp cnt; /* number of valid minor devices */ 



As noted for modules in Chapter 6, configuring a STREAMS driver does not 
require the driver procedures to be externally accessible; only streamtab must be. 
All STREAMS driver procedures would typically be declared static. 

streamtab must be defined as "prefixi nfo", where prefix is the value of the 
prefix field in the master.d file for this driver. The values in name and ID fields in 
the moduleinfo should be unique in the system. The name field is a hook for 
future expansion and is not currently used. The ID is currently used only in log- 
ging and tracing (see Chapter 6 in the Primer). For the example in this chapter, 
the ID is zero. Note that, as in character I/O drivers, extern variables are 
assigned values in the master.d file when configuring drivers or modules (see 
Appendix E). 
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Driver Programming 



There is no read side put or service procedure. The flow control limits for use 
on the write side are 50 and 150 characters. The private Ip structure is indexed 
by the minor device number and contains these elements: 

flags A set of flags. Only one bit is used: BUSY indicates that output is 
active and a device interrupt is pending. 

msg A pointer to the current message being output. 

qptr A back pointer to the write queue. This is needed to find the write 
queue during interrupt processing. 



Driver Open 

The driver open, Ipopen , has the same interface as the module open: 
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Driver Programming 




The Stream flag, sflag , must have the value 0, indicating a normal driver 
open, dev holds both the major and minor device numbers for this port. After 
checking sflag , the open flag, Ipopen extracts the minor device from dev , using the 
minor () macro defined in sysmacros.h. 



NOTE 



The use of major devices, minor devices and minor () macro the may be machine 
dependent. 



The minor device number selects a printer and must be less than lp_cnt. 

The next check, if (q->q_ptr) . . ., determines if this printer is already open. 
In this case, EBUSY is returned to avoid merging printouts from multiple users. 
q_ptr is a driver/module private data pointer. It can be used by the driver for any 
purpose and is initialized to zero by STREAMS. In this example, the driver sets 
the value of q_ptr , in both the read and write queue_t structures, to point to a 
private data structure for the minor device, lpjp[dev 7. 

WR is one of three QUEUE pointer macros. As discussed in the section 
titled "Stream Construction," in Chapter 5, there are no physical pointers between 
QUEUEs, and these macros (see Appendix C) generate the pointer. WR(q) gen- 
erates the write pointer from the read pointer, RD(q) generates the read pointer 
from the write pointer and OTHER (q) generates the mate pointer from either. 
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Driver Processing Procedures 

This example only has a write put procedure: 
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Driver Flush Handling 

The write put procedure, Ipwput , illustrates driver M_FLUSH handling: 

Note that all drivers are expected to incorporate this flush handling. If 
FLUSHW is set, the write message queue is flushed, and also (for this example) 
the leading message (lp->msg). spl5 is used to protect the critical code, assuming 
the device interrupts at level 5. If FLUSHR is set, the read queue is flushed, the 
FLUSHW bit is cleared, and the message is sent upstream using qreply. If 
FLUSHR is not set, the message is discarded. 

The Stream head always performs the following actions on flush requests 
received on the read side from downstream. If FLUSHR is set, messages waiting 
to be sent to user space are flushed. If FLUSHW is set, the Stream head clears 
the FLUSHR bit and sends the M FLUSH message downstream. In this 
manner, a single M_FLUSH message sent from the driver can reach all QUEUES 
in a Stream. A module must send two M_FLUSH messages to have the same 
affect. 

Ipwput enqueues M DATA and M IOCTL (see the section titled "Driver and 
Module Ioctls", below) messages and, if the device is not busy, starts output by 
calling Ipout. Messages types that are not recognized are discarded. 
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Driver Processing Procedures 



Driver Interrupt 

Ipintr is the driver interrupt routine: 
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Driver Processing Procedures 




Ipout simply takes a character from the queue and sends it to the printer. 

The processing is logically similar to the service procedure in Chapter 8. For con- 
venience, the message currently being output is stored in lp->msg. 

Two mythical routines need to be supplied: 

Ipoutchar send a character to the printer and interrupt when complete 
Ipsetopt set the printer interface options 
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Driver and Module loctls 



Drivers and modules interface with ioctl(2) system calls through messages. 
Almost all STREAMS generic ioctls [see streamio(7)] go no further than the 
Stream head. The capability to send an ioctl downstream, is similar to the ioctl 
of character device drivers, is provided by the I_STR ioctl. The Stream head 
processes an I STR by constructing an MIOCTL message (see Appendix B) 
from data provided in the call, and sends that message downstream. 

The user process that issued the I_STR is blocked until a module or driver 
responds with either an M_IOCACK (ack) or M_IOCNAK (nak) message, or 
until the request "times out" after a user specified interval. The STREAMS 
module or driver that generates an ack can also return information to the process. 
If the Stream head does not receive one of these messages in the specified time, 
the ioctl call fails. 

A module that receives an unrecognized M IOCTL message should pass it on 
unchanged. A driver that receives an unrecognized M_IOCTL should nak it. 

Ipout traps M IOCTL messages and calls Ipdoioctl to process them: 
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Driver and Module loctls 




Ipdoioctl illustrates MIOCTL processing: The first part also applies to 
modules. An M_IOCTL message contains a struct iocblk in its first block. The 
first block is followed by zero or more M DATA blocks. The optional M_DATA 
blocks typically contain any user supplied data. 

The form of an iocblk is as follows: 
struct iocblk { 



int 


ioc end; 


/* 


ioctl command type */ 




ushort 


ioc uid; 


/* 


effective uid of user 


*/ 


ushort 


ioc gid; 


/* 


effective gid of user 


*/ 


uint 


ioc id; 


/* 


> 

s 

■H 




uint 


ioc count; 


/* 


count of bytes in data field */ 


int 


ioc error; 


/* 


error code */ 




int 


ioc rval; 


/* 


return value */ 





}; 
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Driver and Module loctls 



ioc cmd contains the command supplied by the user. In this example, only 
one command is recognized, SETOPTIONS. ioc_count contains the number of 
user supplied data bytes. For this example, it must equal the size of a short (2 
bytes). The user data is sent directly to the printer interface using Ipsetopt. 

Next, the M IOCTL message is changed to type MIOCACK and the ioc count 
field is set to zero to indicate that no data is to be returned to the user. Finally, 
the message is sent upstream using qreply. If ioc count was left non-zero, the 
Stream head would copy that many bytes from the 2nd - Nth message blocks into 
the user buffer. 

If the M_IOCTL message is not understood or in error for any reason, the 
driver must set the type to M_IOCNAK and send the message upstream. No 
data can be sent to a user in this case. The Stream head will cause the ioctl call 
to fail with the error number EINVAL. The driver has the option of setting 
ioc error to an alternate error number if desired. 



NOTE 



ioc error can be set to a non-zero value by both M IOCACK 

and M_IOCNAK. This will cause that value to be returned as an error 

number to the process that sent the I STR ioctl. 
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Driver Close 



The driver close clears any message being output. Any messages left on 
message queue will be automatically removed by STREAMS. 
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CHAPTER 10: COMPLETE DRIVER 



Cloning 

The clone mechanism has been developed as a convenience. It allows a user 
to open a driver without specifying the minor device. When a Stream is opened, a 
flag indicating a clone open is tested by the driver open routine. If the flag is set, 
the driver returns an unused minor device number. The clone driver [see 
clone(7)] is a system dependent STREAMS pseudo driver. 

Knowledge of clone driver implementation is not required to use it. A 
description is presented here for completeness and to assist developers who must 
implement their own clone driver. A clone-able device has a device number in 
which the major number corresponds to the clone driver and the minor number 
corresponds to the target driver. When an open (2) system call is made to the 
associated (STREAMS) file, open causes a new Stream to be opened to the clone 
driver and the open procedure in clone to be called with dev set to clone/target. 
The clone open procedure uses minor (dev) to locate the cdevsw entry of the tar- 
get driver. Then, clone modifies the contents of the newly instantiated Stream 
queue ts to those of the target driver and calls the target driver open procedure 
with the Stream flag set to CLONEOPEN. The target driver open responds to 
the CLONEOPEN by returning an unused minor device number. When the 
clone open receives the returned target driver minor device number, it allocates a 
new inode (which has no name in the file system) and associates the minor device 
number with the inode. 
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The loop-around driver is a pseudo-driver that loops data from one open 
Stream to another open Stream. The user processes see the associated files as a 
full duplex pipe. The Streams are not physically linked. The driver is a simple 
multiplexor (see next chapter), which passes messages from one Stream’s write 
QUEUE to the other Stream’s read QUEUE. 

To create a pipe, a process opens two Streams, obtains the minor device 
number associated with one of the returned file descriptors, and sends the device 
number in an I_STR ioctl(2) to the other Stream. For each open, the driver open 
places the passed queue_t pointer in a driver interconnection table, indexed by the 
device number. When the driver later receives the I_STR as an M_IOCTL mes- 
sage, it uses the device number to locate the other Stream’s interconnection table 
entry, and stores the appropriate queue t pointers in both of the Streams’ inter- 
connection table entries. 

Subsequently, when messages other than M IOCTL or M FLUSH are 
received by the driver on either Stream’s write side, the messages are switched to 
the read QUEUE following the driver on the other Stream’s read side. The resul- 
tant logical connection is shown in Figure 10-1. Flow control between the two 
Streams must be handled by special code since STREAMS will not automatically 
propagate flow control information between two Streams that are not physically 
interconnected. 
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Figure 10-1: Loop Around Streams 



The declarations for the driver are: 
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A master.d file to configure the loop driver is shown in Appendix E. The loop 
structure contains the interconnection information for a pair of Streams. 
loop loop is indexed by the minor device number. When a Stream is opened to 
the driver, the address of the corresponding loop loop element is placed in q_ptr 
(private data structure pointer) of the read and write side queue_ts. Since 
STREAMS clears q_ptr when the queue_t is allocated, a NULL value of q_ptr 
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indicates an initial open, loopjoop is used to verify that this Stream is connected 
to another open Stream. 

The open procedure includes canonical clone processing which enables a sin- 
gle file system node to yield a new minor device/inode each time the driver is 
opened: 
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In loopopen , sflag can be CLONEOPEN, indicating that the driver should 
pick a minor device (i.e., the user does not care which minor device is used). In 
this case, the driver scans its private loop loop data structure to find an unused 
minor device number. If sflag has not been set to CLONEOPEN, the passed-in 
minor device is used. 

The return value is the minor device number. In the CLONEOPEN case, 
this value will be used by the clone driver for the newly allocated inode and will 
then be passed to the user. 



Write Put Procedure 

Since the messages are switched to the read QUEUE following the other 
Stream’s read side, the driver needs a put procedure only on its write side: 
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continued 



/* fetch other dev from 2nd message block */ 
to = *(int * ) mp- >b_ cant- >b_rptx ; 

/* 

* More sanity checks. The minor must be in range, open already. 

* Also, this device and the other one must be disconnected. 

*/ 

if (to >= loop_cnt IS to < 0 SI !loop_loop[to] .qptr) { 
error = ENXIO; 
goto iocnak; 

} 

if ( loop->oqptr ! ! loop_loop[to] .oqptr) { 
error = EBUSY; 
goto iocnak; 

} 

/* 

* Cross connect streams via the loop structures 
*/ 

loop->oqptr = RD(loop_loop[to] .qptr) ; 
loop_loqp[ to] .oqptr = RD(q) ; 

/* 

* Return successful ioctl. Set ioc_ count 

* to zero, since there is return no data. 

*/ 

np->b_datap->db_type = M_IOCACK; 
iocp- > ioc_ count = 0; 
qreply(q, np); 
break; 

} 

default: 

error = EINVAL; 
iocnak: 
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loopwput shows another use of an I ISTR ioctl call (see the section titled 
"Driver and Module Ioctls" in Chapter 9). The driver supports a LOOP_SET 
value of ioc_cmd in the iocblk of the MIOCTL message. LOOPSET instructs 
the driver to connect the current open Stream to the Stream indicated in the mes- 
sage. The second block of the 1 M IOCTL message holds an integer that specifies 
the minor device number of the Stream to connect to. 

The driver performs several sanity checks: Does the second block have the 
proper amount of data? Is the "to" device in range? Is the "to" device open? Is 
the current Stream disconnected? Is the "to" Stream disconnected? 

If everything checks out, the read queue t pointers for the two Streams are 
stored in the respective oqptr fields. This cross-connects the two Streams 
indirectly, via loop loop. 

Canonical flush handling is incorporated in the put procedure: 
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Finally, loopwput enqueues all other messages (e.g., MDATA or MPROTO) 
for processing by its service procedure. A check is made to see if the Stream is 
connected. If not, an M_ERROR is sent upstream to the Stream head (see 
below) . 

putctll and putctl (see below) are utilities that allocate a non-data (i.e., not 
M DATA, M PROTO or M PCPROTO) type message, place one byte in the 
message (for putctll) and call the put procedure of the specified QUEUE (see 
Appendix C). 
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Stream Head Messages 

Certain message types (see Appendix B) can be sent upstream by drivers and 
modules to the Stream head where they are translated into actions detectable by 
user process (es). The messages may also modify the state of the Stream head: 

MERROR Causes the Stream head to lock up. Message transmission 

between Stream and user processes is terminated. All 
subsequent system calls except close (2) and poll (2) will 
fail. Also causes an M_FLUSH clearing all message 
queues to be sent downstream by the Stream head. 

MHANGUP Terminates input from a user process to the Stream. All 
subsequent system calls that would send messages down- 
stream will fail. Once the Stream head read message 
queue is empty, EOF is returned on reads. Can also result 
in SIGHUP signal to the process group. 

MSIG/MPCSIG Causes a specified signal to be sent to a process (see 
Chapter 13). 



Service Procedures 

Service procedures are required on both the write and read sides for purposes 
of flow control: 
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The write service procedure, loopwsrv , takes on the canonical form (see 
Chapter 8) with a difference. The QUEUE being written to is not downstream, 
but upstream (found via oqptr) on the other Stream. 

In this case, there is no read side put procedure so the read service procedure, 
looprsrv , is not scheduled by an associated put procedure, as has been done previ- 
ously. looprsrv is scheduled only by being back-enabled when its upstream 
becomes unstuck from flow control blockage. The purpose of the procedure is to 
re-enable the writer {loopwsrv) by using oqptr to find the related queuet. 
loopwsrv can not be directly back-enabled by STREAMS because there is no 
direct queue t linkage between the two Streams. Note that no message ever gets 
queued to the read service procedure. Messages are kept on the write side so that 
flow control can propagate up to the Stream head. There is a defensive check to 
see if the cross-connect has broken, qenable schedules the write side of the other 
Stream. 
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Close 

loopclose breaks the connection between the Streams. 




queue_t *q; 

{ 

register struct loop *loop; 

loop = (struct loop *)q->q ptr; 
loop->qptr = NULL; 



/* 

* If we are connected to another stream, break the 

* linkage, and send a hangup message. 

* The hangup message causes the stream head to fail writes, 

* allow the queued data to be read ccrnpletely, and then 

* return EOF an subsequent reads. 

*/ 

if (loop->oqptr) { 

((struct loop * ) loop->oqptr->q_ptr ) ->qptr = NULL; 
((struct loop * ) loop->oqptr->q_ptr ) ->oqptr = NULL; 
putctl ( loop->oqptr->q_next , M HANGUP); 
loop->oqptr = NULL; 



} 

} 




loopclose sends an M_HANGUP message (see above) up the connected 
Stream to the Stream head. 



NOTE 



This driver can be implemented much more cleanly by actually linking the qjiext 
pointers of the queue t pairs of the two Streams. 
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Multiplexing Configurations 

This chapter describes how STREAMS multiplexing configurations are 
created and discusses multiplexing drivers. A STREAMS multiplexor is a 
pseudo-driver with multiple Streams connected to it. The primary function of the 
driver is to switch messages among the connected Streams. Multiplexor 
configurations are created from user level by system calls. Chapter 6 of the Pri- 
mer contains the required introduction to STREAMS multiplexing. 

STREAMS related system calls are used to set up the "plumbing," or Stream 
interconnections, for multiplexing pseudo-drivers. The subset of these calls that 
allows a user to connect (and disconnect) Streams below a pseudo-driver is 
referred to as the multiplexing facility. This type of connection will be referred to 
as a 1-to-M, or lower, multiplexor configuration (see Figure 6-2 in the Primer). 
This configuration must always contain a multiplexing pseudo-driver, which is 
recognized by STREAMS as having special characteristics. 

Multiple Streams can be connected above a driver by use of open (2) calls. 
This was done for the loop-around driver of the previous chapter and for the 
driver handling multiple minor devices in Chapter 9. There is no difference 
between the connections to these drivers, only the functions performed by the 
driver are different. In the multiplexing case, the driver routes data between mul- 
tiple Streams. In the device driver case, the driver routes data between user 
processes and associated physical ports. Multiplexing with Streams connected 
above will be referred to as an N-to-1, or upper, multiplexor (see Figure 6-1 in 
the Primer). STREAMS does not provide any facilities beyond open and close (2) 
to connect or disconnect upper Streams for multiplexing purposes. 

From the driver’s perspective, upper and lower configurations differ only in 
the way they are initially connected to the driver. The implementation require- 
ments are the same: route the data and handle flow control. All multiplexor 
drivers require special developer-provided software to perform the multiplexing 
data routing and to handle flow control. STREAMS does not directly support 
flow control among multiple Streams. 
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M-to-N multiplexing configurations are implemented by using both of the 
above mechanisms in a driver. Complex multiplexing trees can be created by cas- 
cading multiplexing Streams below one another. 

As discussed in Chapter 9, the multiple Streams that represent minor devices 
are actually distinct Streams in which the driver keeps track of each Stream 
attached to it. The Streams are not really connected to their common driver. 

The same is true for STREAMS multiplexors of any configuration. The multi- 
plexed Streams are distinct and the driver must be implemented to do most of the 
work. As stated above, the only difference between configurations is the manner 
of connecting and disconnecting. Only lower connections have use of the multi- 
plexing facility. 



Connecting Lower Streams 

A lower multiplexor is connected as follows: The initial open to a multiplex- 
ing driver creates a Stream, as in any other driver. As usual, open uses the first 
two streamtab structure entries (see the section titled "Opening a Stream," in 
Chapter 5) to create the driver QUEUES. At this point, the only distinguishing 
characteristic of this Stream are non-NULL entries in the streamtab 
st muxtrwjinit (mux) fields: 



struct streamtab { 
struct qinit 
struct qinit 
struct qinit 
struct qinit 

}; 



*st_rdinit; 
*st_wrinit; 
*st muxrinit; 
*st muxwinit; 



/* defines read QUEUE */ 

/* defines write QUEUE */ 

/* for multiplexing drivers only */ 
/* for multiplexing drivers only */ 



These fields are ignored by the open (see the rightmost Stream in Figure 11-1). 
Any other Stream subsequently opened to this driver will have the same streamtab 
and thereby the same mux fields. 

Next, another file is opened to create a (soon to be) lower Stream. The 
driver for the lower Stream is typically a device driver (see the leftmost Stream in 
Figure 11-1). This Stream has no distinguishing characteristics. It can include 
any driver compatible with the multiplexor. Any modules required on the lower 
Stream must be pushed onto it now. 

Next, this lower Stream is connected below the multiplexing driver with an 
I_LINK ioctl call [see streamio(7)]. As shown in Figure 5-1, all Stream com- 
ponents are constructed in a similar manner. The Stream head points to the 
stream-head-routines as its procedures (known via its queuet) . An I_LINK to 
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the upper Stream, referencing the lower Stream, causes STREAMS to modify the 
contents of the Stream head in the lower Stream. The pointers to the stream- 
head-routines, and other values, in the Stream head are replaced with those con- 
tained in the mux fields of the multiplexing driver’s streamtab. Changing the 
stream-head-routines on the lower Stream means that all subsequent messages 
sent upstream by the lower Stream’s driver will, ultimately, be passed to the put 
procedure designated in stjnuxrinit , the multiplexing driver. The I_LINK also 
establishes this upper Stream as the control Stream for this lower Stream. 
STREAMS remembers the relationship between these two Streams until the 
upper Stream is closed, or the lower Stream is unlinked. 

Finally, the Stream head sends to the multiplexing driver an MIOCTL mes- 
sage with ioc_cmd set to I_LINK (see discussions of the iocblk structure in 
Chapter 9 and Appendix A). The M_DATA part of the M_IOCTL contains a 
linkblk structure: 

struct linkblk { 

qu.eue_t *1 qtop; 
queuejt *1 qbot; 
int 1 index; 

}; 

The multiplexing driver stores information from the linkblk in private storage and 
returns an M_IOCACK message (ack) . I index is returned to the process 
requesting the ILINK. This value can be used later by the process to disconnect 
this Stream, as described below, linkblk contents are further discussed below. 

An IJLINK is required for each lower Stream connected to the driver. Addi- 
tional upper Streams can be connected to the multiplexing driver by open calls. 
Any message type can be sent from a lower Stream to user process (es) along any 
of the upper Streams. The upper Stream (s) provides the only interface between 
the user process (es) and the multiplexor. 

Note that no direct data structure linkage is established for the linked 
Streams. The qjiext pointers of the lower Stream still appear to connect with a 
Stream head. Messages flowing upstream from a lower driver (a device driver or 
another multiplexor) will enter the multiplexing driver (i.e., Stream head) put 
procedure with l qbot as the queue t value. The multiplexing driver has to route 
the messages to the appropriate upper (or lower) Stream. Similarly, a message 
coming downstream from user space on the control, or any other, upper Stream 
has to be processed and routed, if required, by the driver. 



/* lowest level write queue of upper stream */ 
/* highest level write queue of lower stream */ 
/* system-unique index for lower stream. */ 
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Also note that the lower Stream (see the headers and file descriptors in Fig- 
ure 11-2) is no longer accessible from user space. This causes all system calls to 
the lower Stream to return EINVAL, with the exception of close. This is why all 
modules have to be in place before the lower Stream is linked to the multiplexing 
driver. As a general rule, the lower Stream file should be closed after it is linked 
(see following section). This does not disturb the multiplexing configuration. 

Finally, note that the absence of direct linkage between the upper and lower 
Streams means that STREAMS flow control has to be handled by special code in 
the multiplexing driver. The flow control mechanism cannot see across the driver. 

In general, multiplexing drivers should be implemented so that new Streams 
can be dynamically connected to, and existing Streams disconnected from, the 
driver without interfering with its ongoing operation. The number of Streams 
that can be connected to a multiplexor is developer dependent. However, there is 
a system limit, NMUXLINK (see Appendix E), to the number of Streams that 
can be linked in the system. 



Disconnecting Lower Streams 

Dismantling a lower multiplexor is accomplished by disconnecting (unlinking) 
the lower Streams. Unlinking can be initiated in three ways: an IJJNLINK ioctl 
referencing a specific Stream, an I_UNLINK indicating all lower Streams, or the 
last close (i.e., causes the associated file to be closed) of the control Stream. As 
in the link, an unlink sends a linkblk structure to the driver in an M_IOCTL mes- 
sage. The IJJNLINK call, which unlinks a single Stream, uses the IJndex value 
returned in the I_LINK to specify the lower Stream to be unlinked. The latter 
two calls must designate a file corresponding to a control Stream which causes all 
the lower Streams that were previously linked by this control Stream to be 
unlinked. However, the driver sees a series of individual unlinks. 

If the file descriptor for a lower Stream was previously closed, a subsequent 
unlink will automatically close the Stream. Otherwise, the lower Stream must be 
closed by close following the unlink. STREAMS will automatically dismantle all 
cascaded multiplexors (below other multiplexing Streams) if their controlling 
Stream is closed. An IJJNLINK will leave lower, cascaded multiplexing 
Streams intact unless the Stream file descriptor was previously closed. 
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This section describes an example of multiplexor construction and usage. A 
multiplexing configuration similar to the Internet of Figure 6-2 in the Primer is 
discussed. Figure 11-1 shows the Streams before their connection to create the 
multiplexing configuration of Figure 11-2. Multiple upper and lower Streams 
interface to the multiplexor driver. The user processes of Figure 11-2 are not 
shown in Figure 11-1. 



Setup and Supervisory Process 




Figure 11-1: Internet Multiplexor Before Connecting 



The Ethernet, LAPB and IEEE 802.2 device drivers terminate links to other 
nodes. IP (Internet Protocol) is a multiplexor driver. IP switches datagrams 
among the various nodes or sends them upstream to a user (s) in the system. The 
Net modules would typically provide a convergence function which matches the 
IP and device driver interface. 
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Figure 11-1 depicts only a portion of the full, larger Stream. As shown in the 
dotted rectangle above the IP multiplexor, there generally would be an upper TCP 
multiplexor, additional modules and, possibly, additional multiplexors in the 
Stream. Multiplexors could also be cascaded below the IP driver if the device 
drivers were replaced by multiplexor drivers. 




Figure 11-2: Internet Multiplexor After Connecting 
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Streams A, B and C are opened by the process, and modules are pushed as 
needed. Two upper Streams are opened to the IP multiplexor. The rightmost 
Stream represents multiple Streams, each connected to a process using the net- 
work. The Stream second from the right provides a direct path to the multiplexor 
for supervisory functions. It is the control Stream, leading to a process which sets 
up and supervises this configuration. It is always directly connected to the IP 
driver. Although not shown, modules can be pushed on the control Stream. 

After the Streams are opened, the supervisory process typically transfers rout- 
ing information to the IP drivers (and any other multiplexors above the IP), and 
initializes the links. As each link becomes operational, its Stream is connected 
below the IP driver. If a more complex multiplexing configuration is required, the 
IP multiplexor Stream with all its connected links can be connected below another 
multiplexor driver. 

As shown in Figure 11-2, the file descriptors for the lower device driver 
Streams are left dangling. The primary purpose in creating these Streams was to 
provide parts for the multiplexor. Those not used for control and not required for 
error recovery (by reconnecting them through an IJJNLINK ioctl) have no fur- 
ther function. As stated above, these lower Streams can be closed to free the file 
descriptor without any effect on the multiplexor. A setup process installing a 
configuration containing a large number of drivers should do this to avoid running 
out of file descriptors. 
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This section contains an example of a multiplexing driver that implements an 
N-to-1 configuration, similar to that of Figure 6-3 in the Primer. This 
configuration might be used for terminal windows, where each transmission to or 
from the terminal identifies the window. This resembles a typical device driver, 
with two differences: the device handling functions are performed by a separate 
driver, connected as a lower Stream, and the device information (i.e., relevant 
user process) is contained in the input data rather than in an interrupt call. 

Each upper Stream is connected by an open (2), identical to the driver of 
Chapter 9. A single lower Stream is opened and then it is linked by use of the 
multiplexing facility. This lower Stream might connect to the tty driver. The 
implementation of this example is a foundation for an M to N multiplexor. 

As in the loop-around driver, flow control requires the use of standard and 
special code, since physical connectivity among the Streams is broken at the 
driver. Different approaches are used for flow control on the lower Stream, for 
messages coming upstream from the device driver, and on the upper Streams, for 
messages coming downstream from the user processes. 

The multiplexor declarations are: 
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The four streamtab entries correspond to the upper read, upper write, lower 
read, and lower write qinit structures. The multiplexing qinit structures replace 
those in each (in this case there is only one) lower Stream head after the I_LINK 
has completed successfully. In a multiplexing configuration, the processing per- 
formed by the multiplexing driver can be partitioned between the upper and lower 
QUEUEs. There must be an upper Stream write, and lower Stream read, put 
procedures. In general, only upper write side and lower read side procedures are 
used. Application specific flow control requirements might modify this. If the 
QUEUE procedures of the opposite upper/lower QUEUE are not needed, the 
QUEUE can be skipped over, and the message put to the following QUEUE. 

In the example, the upper read side procedures are not used. The lower 
Stream read QUEUE put procedure transfers the message directly to the read 
QUEUE upstream from the multiplexor. There is no lower write put procedure 
because the upper write put procedure directly feeds the lower write service pro- 
cedure, as described below. 

The driver uses a private data structure, mux. muxjnuxldev ] points back to 
the opened upper read QUEUE. This is used to route messages coming upstream 
from the driver to the appropriate upper QUEUE. It is also used to find a free 
minor device for a CLONEOPEN driver open case. 

The upper QUEUE open contains the canonical driver open code: 
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muxopen checks for a clone or ordinary open call. It loads q_ptr to point at 
the muxjnuxl ] structure. 

The core multiplexor processing is the following: downstream data written to 
an upper Stream is queued on the corresponding upper write message queue. This 
allows flow control to propagate towards the Stream head for each upper Stream. 
However, there is no service procedure on the upper write side. All M DATA 
messages from all the upper message queues are ultimately dequeued by the ser- 
vice procedure on the lower (linked) write side. The upper write Streams are ser- 
viced in a round-robin fashion by the lower write service procedure. A lower 
write service procedure, rather than a write put procedure, is used so that flow 
control, coming up from the driver below, may be handled. 
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On the lower read side, data coming up the lower Stream is passed to the 
lower read put procedure. The procedure routes the data to an upper Stream 
based on the first byte of the message. This byte holds the minor device number 
of an upper Stream. The put procedure handles flow control by testing the upper 
Stream at the first upper read QUEUE beyond the driver. That is, the put pro- 
cedure treats the Stream component above the driver as the next QUEUE. 




Figure 11-3: Example Multiplexor Configuration 



This is shown (sort of) in Figure 11-3. Multiplexor Routines are all the above 
procedures. U1 and U2 are queue_t pairs, each including a write queue_t pointed 
at by an I qtop in a linkblk (see beginning of this chapter) . L is the queue_t pair 
which contains the write queue_t pointed at by l_qbot. N1 and N2 are the 
modules (or Stream head or another multiplexing driver) seen by L when read 
side messages are sent upstream. 



Upper Write Put Procedure 

muxuwput, the upper QUEUE write put procedure, traps ioctls, in particular 
I LINK and I UNLINK: 
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static int muxuwput(q, mp) 
queue_t *q; 
mblkt *np; 

{ 



int s; 

struct mux *mux; 

mux = (struct mux *)q->q ptr; 
switch (np->b_da tap- >db_ type ) { 
case M IOCTL: { 

struct iocblk *iocp; 
struct linkblk *linkp; 



/* 

* Ioctl. Only channel 0 can do ioctls. Two 

* calls are recognized: LINK, and UNLINK 
*/ 

if (mux != muxjnux) 
goto iocnak; 

iocp = (struct iocblk *) mp->b_rptr; 
switch ( iocp->ioc_cmd) { 
case I LINK: 



/* 

* Link. The data contains a linkblk structure 

* Remember the bottom queue in muxbot. 

*/ 

if (muxbot != NULL) 
goto iocnak; 

linkp = (struct linkblk *) mp->b_cant->b_rptr; 
muxbot * lihkp->l_qbot ; 
muxerr = 0; 

mp->b_datap->db_type = M IOCACK; 
iocp- >ioc_ count = 0; 
qreply(q, mp); 
break; 

case I UNLINK: 
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First, there is a check to enforce that the Stream associated with minor device 
0 will be the single, controlling Stream. Ioctls are only accepted on this Stream. 
As described previously, a controlling Stream is the one that issues the I LINK. 
Having a single control Stream is a recommended practice. IJLINK and 
I_UNLINK include a linkblk structure, described previously, containing: 

ljl to P The upper write QUEUE from which the ioctl is coming. It should 
always equal q. 

Iqbot The new lower write QUEUE. It is the former Stream head write 
QUEUE. It is of most interest since that is where the multiplexor 
gets and puts its data. 
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IJndex A unique (system wide) identifier for the link. It can be used for 
routing, or during selective unlinks, as described above. Since the 
example only supports a single link, IJndex is not used. 

For IJLINK, I qbot is saved in muxbot and an ack is generated. From this 
point on, until an IJJNLINK occurs, data from upper queues will be routed 
through muxbot. Note that when an I LINK, is received, the lower Stream has 
already been connected. This allows the driver to send messages downstream to 
perform any initialization functions. Returning an M IOCNAK message (nak) 
in response to an IJLINK will cause the lower Stream to be disconnected. 

The IJJNLINK handling code nulls out muxbot and generates an ack. A 
nak should not be returned to an I JJNLINK. The Stream head assures that the 
lower Stream is connected to a multiplexor before sending an IJJNLINK 
M IOCTL. 

muxuwput handles M FLUSH messages as a normal driver would: 
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M_DATA messages are not placed on the lower write message queue. They 
are queued on the upper write message queue, putq recognizes the absence of the 
upper service procedure and does not schedule the QUEUE. Then, the lower ser- 
vice procedure, muxlwsrv is scheduled with qenable (see Appendix C) to start 
output. This is similar to starting output on a device driver. Note that 
muxuwput can not access muxlwsrv (the lower QUEUE write service procedure, 
contained in muxbot) by the conventional STREAMS calls, putq or putnext (to a 
muxlwput ) . Both calls require that a message be passed, but the messages 
remain on the upper Stream. 



Lower QUEUE Write Service Procedure 

muxlwsrv, the lower (linked) queue write service procedure is scheduled 
directly from the upper service procedures. It is also scheduled from the lower 
Stream, by being back-enabled when the lower Stream becomes unblocked from 
downstream flow control. 
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muxlwsrv takes data from the upper queues and puts it out through muxbot. 
The algorithm used is simple round robin. While we can put to muxbot- 
>q_next , we select an upper QUEUE (via get next _q) and move a message from 
it to muxbot. Each message is prepended by a one byte header that indicates 
which upper Stream it came from. 
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Multiplexing Driver 



Finding messages on upper write queues is handled by get_next_q : 
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Multiplexing Driver 



getjiext q searches the upper queues in a round robin fashion looking for the 
first one containing a message. It returns the queue_t pointer or NULL if there is 
no work to do. 



Lower Read Put Procedure 

The lower (linked) queue read put procedure is: 
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muxlrput receives messages from the linked Stream. In this case, it is acting 
as a Stream head. It handles M_FLUSH messages. Note the code is reversed 
from that of a driver, handling M_FLUSH messages from upstream. 

muxlrput also handles MERROR and M HANGUP messages. If one is 
received, it locks-up the upper Streams. 

M_DATA messages are routed by looking at the first data byte of the mes- 
sage. This byte contains the minor device of the upper Stream. If removing this 
byte causes the leading block to be empty, and more blocks follow, the block is 
discarded. This is done because the Stream head interprets a leading zero length 
block as an EOF [see read (2)]. Several sanity checks are made: Does the mes- 
sage have at least one byte? Is the device in range? Is the upper Stream open? 

Is the upper Stream not full? 

This mux does not do end-to-end flow control. It is merely a router (like the 
Department of Defense’s IP protocol) . If everything checks out, the message is 
put to the proper upper QUEUE. Otherwise, the message is silently discarded. 

The upper Stream close routine simply clears the mux entry so this queue will 
no longer be found by get next _queue: 
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Definition 

STREAMS provides the means to implement a service interface between any 
two components in a Stream, and between a user process and the topmost module 
in the Stream. A service interface is defined at the boundary between a service 
user and a service provider (see Figure 4-2). A service interface is a set of primi- 
tives and the rules for the allowable sequences of primitives across the boundary. 
These rules are typically represented by a state machine. In STREAMS, the ser- 
vice user and provider are implemented in a module, driver, or user process. The 
primitives are carried bidirectionally between a service user and provider in 
MJPROTO and M_PCPROTO (generically, PROTO) messages. M_PCPROTO 
is the priority version of M_PROTO. 



Message Usage 

As described in Appendix B, PROTO messages can be multi-block, with the 
second through last blocks of type M_DATA. The first block in a PROTO mes- 
sage contains the control part of the primitive in a form agreed upon by the user 
and provider and the block is not intended to carry protocol headers. (Although 
its use is not recommended, upstream PROTO messages can have multiple 
PROTO blocks at the start of the message, getmsg will compact the blocks into a 
single control part when sending to a user process.) The M_DATA block(s) con- 
tains any data part associated with the primitive. The data part may be processed 
in a module that receives it, or it may be sent to the next Stream component, 
along with any data generated by the module. The contents of PROTO messages 
and their allowable sequences are determined by the service interface specification. 

PROTO messages can be sent bidirectionally (up and downstream) on a 
Stream and bidirectionally between a Stream and a user process. putmsg(2) and 
getmsg (2) system calls are analogous, respectively, to write (2) and read (2) except 
that the former allow both data and control parts to be (separately) passed, and 
they observe message boundary alignment across the user-Stream boundary, 
putmsg and getmsg separately copy the control part (M PROTO or 
M_PCPROTO block) and data part (M_DATA blocks) between the Stream and 
user process. 
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Definition 



An MPCPROTO message is normally used to acknowledge M PROTO 
messages and not to carry protocol expedited data. M PCPROTO insures that 
the acknowledgement reaches the service user before any other message. If the 
service user is a user process, the Stream head will only store a single 
M PCPROTO message, and discard subsequent M PCPROTO messages until 
the first one is read with getmsg(2). 

The following rules pertain to service interfaces: 

■ Modules and drivers that support a service interface must act upon all 
PROTO messages and not pass them through. 

■ Modules may be inserted between a service user and a service provider to 
manipulate the data part as it passes between them. However, these 
modules may not alter the contents of the control part (PROTO block, first 
message block) nor alter the boundaries of the control or data parts. That 
is, the message blocks comprising the data part may be changed, but the 
message may not be split into separate messages nor combined with other 
messages. 

In addition, modules and drivers must observe the rule that priority messages are 
not subject to flow control and forward them accordingly (e.g., see the beginning 
of modwsrv in Chapter 8) . Priority messages also bypass flow control at the 
user-Stream boundary [e.g., see putmsg(2)]. 
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Example 



The example below is part of a module which illustrates the concept of a ser- 
vice interface. The module implements a simple datagram interface and mirrors 
the example in Chapter 4. 



Declarations 

The service interface primitives are defined in the declarations: 



#include "sys/types.h" 
#include "sys/param.h" 
#include "sys/stream.h" 
#include "sys/ermo.h" 



* Primitives initiated by the service user: 

*/ 

^define BIND REQ 1 /* bind request */ 

#define UNITDATA_REQ 2 /* unitdata request */ 

/* 

* Primitives initiated by the service provider: 

*/ 

#def ine OK_ACK 3 /* bind acknowledgment */ 

#define ERRQR_ACK 4 /* error acknowledgment */ 

#define UNITDATA_IND 5 /* unitdata indication */ 

/* 

* The following structures define the format of the 

* stream message block of the above primitives. 

*/ 

struct bind_req { /* bind request */ 

long PRIM_type; /* always BIND_REQ */ 

long BIND_addr ; /* addr to bind */ 

}; 

struct unitdata_req { /* unitdata request */ 
long PRIM_type; /* always UNITDATA_REQ */ 

long DEST addr; /* dest addr */ 



struct ok ack { 
long PRIM type; 

}; 



/* ok acknowledgment */ 
/* always OK ACK */ 
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Example 




In general, the M_PROTO or M_PCPROTO block is described by a data 
structure containing the service interface information. In this example, union 
primitives is that structure. 

Two commands are recognized by the module: 

BIND REQ Give this Stream a protocol address, i.e. give it a name on 

the network. After a BIND_REQ is completed, 
datagrams from other senders will find their way through 
the network to this particular Stream. 
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Example 



UNITDATA_REQ Send a datagram to the specified address. 

Three messages are generated: 

OK_ACK A positive acknowledgement (ack) of BIND_REQ. 

ERROR ACK A negative acknowledgement of BINDREQ. 

UNITDATA_IND A datagram from the network has been received (this code 
is not shown). 

The ack of a BIND_REQ informs the user that the request was syntactically 
correct (or incorrect if ERROR_ACK) . The receipt of a BIND_REQ is ack- 
nowledged with an M_PCPROTO to insure that the acknowledgement reaches the 
user before any other message. For example, a UNITDATA IND could come 
through before the bind has completed, and the user would get confused. 

The driver uses a per-minor device data structure, dgproto , which contains 
the following: 

state current state of the Stream (endpoint) IDLE or BOUND 

addr network address that has been bound to this Stream 

It is assumed (though not shown) that the module open procedure sets the 
write queue q_ptr to point at one of these structures. 



Service Interface Procedure 

The write put procedure is: 
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continued 



default: 

/* don't understand it */ 

np->b_datap->db_type = M_ERROR; 

mp->b_rptr = mp->b_wptr = mp->b_datap->db_base ; 

*mp->b_wptr++ = EPROTO; 
qreply(q, mp) ; 
break; 

case M_FLUSH: 

/* standard flush handling goes here . . . */ 
break; 

case M PROTO: 

/* Protocol message -> user request */ 

proto = (union primitives *) mp->b rptr; 

switch ( proto- > type) { 
default: 

mp- >b_da tap- >db_ type = M ERROR; 

mp->b_rptr = mp->b_wptr = mp->b datap->db base; 

*rnp->b wptr++ = EPROTO; 
qreplyTq, mp); 
return; 

case BIND REQ: 

if ( dgproto-> state != IDLE) { 
err = EINVAL; 
goto error ack; 

} 

if (mp->b_wptr - mp->b_rptr != sizeof ( struct bind_req) ) { 
err = EINVAL; 
goto error _ack; 

} 

if (err = chkaddr(proto->bind_req.BIND_addr) ) 
goto error_ack; 

dgproto- > state = BOUND; 

dgproto- >addr = proto- >bind_req . BIND_addr ; 
mp->b_datap->db type = M_FCPROTO; 
proto- > type = OK_ACK; 

mp->b_wptr = mp->b_rptr + sizeof ( struct ok_ack) ; 

qreply(q, mp) ; 

break; 
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The write put procedure switches on the message type. The only types 
accepted are MFLUSH and M PROTO. For MFLUSH messages, the driver 
will perform the canonical flush handling (not shown) . For M_PROTO messages, 
the driver assumes the message block contains a union primitive and switches on 
the type field. Two types are understood: BIND_REQ, and UNITDATA REQ. 
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Example 



For a BINDREQ, the current state is checked; it must be IDLE. Next, the 
message size is checked. If it is the correct size, the passed-in address is verified 
for legality by calling chkaddr. If everything checks, the incoming message is 
converted into an OK ACK and sent upstream. If there was any error, the 
incoming message is converted into an ERRORACK and sent upstream. 

For UNITDATA REQ, the state is also checked; it must be BOUND. As 
above, the message size and destination address are checked. If there is any 
error, the message is simply discarded. (This action may seem rash, but it is in 
accordance with the interface specification, which is not shown. Another 
specification might call for the generation of a UNITDATA ERROR indication.) 
If all is well, the data part of the message, if it exists, is put on the queue, and the 
lower half of the driver is started. 

If the write put procedure receives a message type that it does not under- 
stand, either a bad b datap->db_type or bad proto->type, the message is 
converted into an M_ERROR message and sent upstream. 

Another piece of code not shown is the generation of UNITDATA_IND mes- 
sages. This would normally occur in the device interrupt if this is a hardware 
driver (like STARLAN) or in the lower read put procedure if this is a multi- 
plexor. The algorithm is simple: The data part of the message is prepended by an 
M_PROTO message block that contains a unitdatajnd structure and sent 
upstream. 
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CHAPTER 13: ADVANCED TOPICS 



Recovering From No Buffers 

The bufcall utility (see Appendix C) is used to recover from an allocb failure. 
The call syntax is as follows: 

bufcall ( size , pri , func , arg) ; 
int size, pri, (*func)(); 
long arg; 

bufcall will call ( *func ) (arg) when a buffer of size bytes at pri priority is 
available. When func is called, it has no user context and must return without 
sleeping. Also, because of interrupt processing, there is no guarantee that when 
func is called, a buffer will actually be available (someone else may steal it), buf- 
call returns 1 on success, indicating that the request has been successfully 
recorded, or 0 on failure. On a failure return, the requested function will never 
be called. 

V Care must be taken to avoid deadlock when holding resources while waiting for 
bufcall to call (* func) (arg) . bufcall should be used sparingly. 

Two examples are provided. Example one is a device receive interrupt 
handler: 
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Recovering From No Buffers 




dev_rintr is called when the device has posted a receive interrupt. The code 
retrieves the data from the device (not shown) . dev_rintr must then give the 
device another buffer to fill by a call to dev_reJoad , which calls allocb with the 
appropriate buffer size (DEVBLKSZ, definition not shown) and priority. If 
allocb fails, devjejoad uses bufcall to call itself when STREAMS determines a 
buffer of the appropriate size and priority is available. 



NOTE 



Since bufcall may fail, there is still a chance that the device may hang. A better 
strategy, in the event bufcall fails, would be to discard the current input message 
and resubmit that buffer to the device. Losing input data is generally better than 
hanging. 



The second example is a write service procedure, modjvsrv , which needs to 
prepend each output message with a header (similar to the multiplexor example 
of Chapter 11). mod_wsrv illustrates a case for potential deadlock: 
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Recovering From No Buffers 




However, if allocb fails, modjwsrv wants to recover without loss of data ands 
calls bufcall. In this case, the routine passed to bufcall is qenable (see below and 
Appendix C). When a buffer is available (of size HDRSZ, definition not shown), 
the service procedure will be automatically re-enabled. Before exiting, the current 
message is put back on the queue. This example deals with bufcall failure by dis- 
carding the current message and continuing in the service procedure loop. 
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Advanced Flow Control 



Streams provides mechanisms to alter the normal queue scheduling process, 
putq will not schedule a QUEUE if noenable (q) had been previously called for 
this QUEUE, noenable instructs putq to queue the message when called by this 
QUEUE, but not to schedule the service procedure, noenable does not prevent the 
QUEUE from being scheduled by a flow control back-enable. The inverse of 
noenable is enableok(q). 

An example of this is driver upstream flow control. Although device drivers 
typically discard input when unable to send it to a user process, STREAMS 
allows driver read side flow control, possibly for handling temporary upstream 
blocks. This is done through a driver read service procedure which is disabled 
during the driver open with noenable. If the driver input interrupt routine deter- 
mines messages can be sent upstream (from canput), it sends the message with 
putnext. Otherwise, it calls putq to queue the message. The message waits on the 
message queue (possibly with queue length checked when new messages are 
enqueued by the interrupt routine) until the upstream QUEUE becomes 
unblocked. When the blockage abates, STREAMS back-enables the driver read 
service procedure. The service procedure sends the messages upstream using getq 
and canput, as in Chapter 8. This is similar to looprsrv in Chapter 10 where the 
service procedure is present only for flow control. 

qenable, another flow control utility, allows a module or driver to cause one of 
its QUEUES, or another module’s QUEUEs, to be scheduled. In addition to the 
usage shown in Chapters 10 and 11, qenable might be used when a module or 
driver wants to delay message processing for some reason. An example of this is 
a buffer module that gathers messages in its message queue and forwards them as 
a single, larger message. This module uses noenable to inhibit its service pro- 
cedure and queues messages with its put procedure until a certain byte count or 
"in queue" time has been reached. When either of these conditions is met, the put 
procedure calls qenable to cause its service procedure to run. 

Another example is a communication line discipline module that implements 
end-to-end (i.e., to a remote system) flow control. Outbound data is held on the 
write side message queue until the read side receives a transmit window from the 
remote end of the network. Then, the read side schedules the write side service 
procedure to run. 
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Signals 

STREAMS allows modules and drivers to cause a signal to be sent to user 
process (es) through an M SIG or M_PCSIG message (see Appendix B) sent 
upstream. M PCSIG is a priority version of M_SIG. For both messages, the 
first byte of the message specifies the signal for the Stream head to generate. If 
the signal is not SIGPOLL [see signal(2) and sigset(2)], then the signal is sent to 
the process group associated with the Stream (see below). If the signal is SIG- 
POLL, the signal is only sent to processes that have registered for the signal by 
using the ISETSIG ioctl(2) [also see streamio(7)] call. 

A process group is associated with a Stream during the open of the driver or 
module. If u.ujtyp is NULL prior to the driver or module open call, the Stream 
head checks u.ujtyp after the driver or module open call returns. If u.ujtyp is 
non-zero, it is assumed to point to a short that holds the process group ID for sig- 
naling. The process group and indirect TTY (/dev/tty) inode are recorded in the 
Stream head. 

If the driver or module wants to have a process group associated with the 
Stream, it should include code of the following form in its open procedure: 



pp = u.u procp; /* pointer to process structure */ 
pdp = . . . /* private data pointer */ 



if (pp->p_pid == pp->p_pgrp 
&&. u.u_ttyp == NULL 
&& pdp->pgrp == 0) { 



/* process group leader */ 

/* with no controlling tty */ 

/* and this stream is unassigned */ 



/* assign controlling tty */ 



u.u_ttyp = &pdp->pgrp; 
pdp->pgrp = pp->p pgrp; 
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Signals 



A private data structure containing a short pgrp element is required. 

M_SIG can be used by modules or drivers that wish to insert an explicit 
inband signal into a message stream. For example, an MSIG message can be 
sent to the user process immediately before a particular service interface message 
to gain the immediate attention of the user process. When the M SIG reaches 
the head of the Stream head read message queue, a signal will be generated and 
the M SIG message will be removed. This leaves the service interface message as 
the next message to be processed by the user. Use of M_SIG would typically be 
defined as part of the service interface of the driver or module. 
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Control of Stream Head Processing 

The M_SETOPTS message (see Appendix B) allows a driver or module to 
exercise control over certain Stream head processing. An M_SETOPTS can be 
sent upstream at any time. The Stream head responds to the message by altering 
the processing associated with certain system calls. The options to be modified 
are specified by the contents of the stroptions structure (see Appendix B) con- 
tained in the message. 

Six Stream head characteristics can be modified. As described in Appendix 
B, four correspond to fields contained in queue_t (min/max packet sizes and 
high/low water marks) . The other two are discussed here. 



Read Options 

The value for read options ( sojeadopt ) corresponds to the three modes a user 
can set via the I SRDOPT ioctl (see streamio) call: 

byte-stream (RNORM) 

The read (2) call completes when the byte count is satisfied, the 
Stream head read queue becomes empty, or a zero length mes- 
sage is encountered. In the last case, the zero length message is 
put back on the queue. A subsequent read will return 0 bytes. 

message non-discard (RMSGN) 

The read call completes when the byte count is satisfied or at a 
message boundary, whichever comes first. Any data remaining in 
the message is put back on the Stream head read queue. 

message discard (RMSGD) 

The read call completes when the byte count is satisfied or at a 
message boundary. Any data remaining in the message is dis- 
carded. 

Byte-stream mode approximately models pipe data transfer. Message non- 
discard mode approximately models a TTY in canonical mode. 
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Control of Stream Head Processing 



Write Offset 

The value for write offset (so_wrojf) is a hook to allow more efficient data 
handling. It works as follows: In every data message generated by a write (2) sys- 
tem call and in the first M DATA block of the data portion of every message 
generated by a putmsg(2) call, the Stream head will leave sojvroff bytes of space 
at the beginning of the message block. Expressed as a C language construct: 

bp->b_rptr = bp->b_datap->db_base +write offset. 

The write offset value must be smaller than the maximum STREAMS message 
size, STRMSGSZ (see the section titled "Tunable Parameters" in Appendix E). 

In certain cases (e.g., if a buffer large enough to hold the offset+data is not 
currently available), the write offset might not be included in the block. To be 
general, modules and drivers should not assume that the offset exists in a message, 
but should always check the message. 

The intended use of write offset is to leave room for a module or a driver to 
place a protocol header before user data in the message rather than by allocating 
and prepending a separate message. This feature is not general, and its use is 
discouraged. A more general technique is to put protocol header information in a 
separate message block and link the user data to it. 
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Appendix A: Kernel Structures 



This appendix summarizes previously described kernel structures commonly 
encountered in STREAMS module and driver development. 

STREAMS kernel structures are contained in <sys/stream.h> 



NOTE 



These and other STREAMS structures (shown in bold) contained in both parts of 
this guide will remain fixed in subsequent releases of UNIX System V, subject to 
the following: The offset of all defined elements in each structure will not change. 
However, the size of the structure may be increased to add new elements. 



streamtab 



As discussed in Chapter 5, this structure defines a module or driver: 



struct streamtab { 



struct qinit 


*st rdinit; 


/* 


struct qinit 


*st_wrinit ; 


/* 


struct qinit 


*st muxrinit; 


/* 


struct qinit 


*st muxwinit; 


/* 



}; 



defines read QUEUE */ 
defines write QUEUE */ 
for multiplexing drivers only */ 
for multiplexing drivers only */ 
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QUEUE Structures 

Two sets of QUEUE structures form a module. The structures, discussed in 
Chapters 5 and 8, are queuet, qinit, module Jnfo and, optionally, modulestat: 

struct queue { 

struct qinit *q_qinfo; /* procedures and limits for queue */ 
struct msgb *q_first; /* head of message queue for this QUEUE */ 
struct msgb *q_last; /* tail of message queue for this QUEUE */ 
struct queue *q_next ; /* next QUEUE in Stream*/ 

struct queue *q_link; /* link to next QUEUE on STREAMS scheduling queue */ 
caddr t q_ptr ; /* to private data structure */ 

ushort q_ count; /* weighted count of characters on message queue */ 

ushort q_flag; /* QUEUE state */ 

short qjninpsz; /* min packet size accepted by this QUEUE */ 

short q_maxpsz; /* max packet size accepted by this QUEUE */ 

ushort q hiwat; /* message queue high water mark, for flow control */ 

ushort q lowat; /* message queue low water mark, for flow control */ 

}; 

typedef struct queue queue_t; 

When a queue_t pair is allocated, their contents are zero unless specifically 
initialized. The following fields are initialized: 

■ q_qinfo - from streamtab.st_[rd/wr]init (or st mux[rw]init) 

■ qjninpsz, qjnaxpsz, qjiiwat, qjowat - from module_info 

■ q_ptr - optionally, by the driver/module open routine 

struct qinit { 

int (*qi_putp) ( ) ; /* put procedure */ 

int (*qi_srvp) ( ) ; /* service procedure */ 

int (*qi_qopen) ( ) ; /* called on each open or a push */ 

int ( *qi_qclose ) ( ) ; /* called on last close or a pop */ 

int (*qi_qadmin) ( ) ; /* reserved for future use */ 

struct module_info *qi_minfo; /* information structure */ 

struct module_stat *qi_mstat; /* statistics structure - optional */ 

}; 
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struct module_info { 
ushort mi_idnum; 
char *mi idname ; 
short mi_minpsz ; 

short mi_maxpsz ; 

short mi hiwat; 
ushort mi_ lowat ; 

}; 

struct modulestat { 
long ms_pcnt; 

long ms _ sent ; 

long msoent ; 

long ms_ccnt; 

long ms aent; 

char *ms_xptr ; 
short ms xsize ; 
}; 



/* module ID number */ 

/* module name */ 

/* min packet size accepted, for developer use */ 
/* max packet size accepted, for developer use */ 
/* hi-water mark, for flow control */ 

/* lo-water mark, for flow control */ 



/* count of calls to put proc */ 

/* count of calls to service proc */ 

/* count of calls to open proc */ 

/* count of calls to close proc */ 

/* count of calls to admin proc */ 

/* pointer to private statistics */ 

/* length of private statistics buffer */ 



Note that in the event these counts are calculated by modules or drivers, the 
counts will be cumulative over all instantiations of modules with the same fmodsw 
entry and drivers with the same edevsw entry. 
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Message Structures 

As described in Chapter 7, a message is composed of a linked list of triples, 
consisting of two structures and a data buffer: 

struct msgb { 

struct msgb *b_next; /* next message on queue */ 

struct msgb *b_prev; /* previous message on queue */ 

struct msgb *b_cont ; /* next message block of message */ 

unsigned char *b_rptr ; /* first unread data byte in buffer */ 

unsigned char *b_wptr ; /* first unwritten data byte in buffer */ 

struct da tab *b da tap; /* data block */ 

}; 

typedef struct msgb mblk t; 
struct da tab { 

struct datab *db_freep; /* used internally */ 
unsigned char *db base; /* first byte of buffer * */ 
unsigned char *db_lim; /* last byte+1 of buffer */ 

unsigned char db ref; /* count of messages pointing to this block */ 
unsigned char db_type; /* message type */ 
unsigned char db_class; /* used internally */ 

}; 

typedef struct datab dblk_t; 

iocblk 

As described in Chapter 9 and Appendix B, this is contained in an M_IOCTL 
message block: 

struct iocblk { 

int ioc_cmd; /* ioctl command type */ 

ushort ioc_uid; /* effective uid of user */ 

ushort ioc_gid; /* effective gid of user */ 

uint ioc_id; /* ioctl id */ 

uint ioc_count; /* count of bytes in data field */ 
int ioc_ error; /* error code */ 
int ioc_rval; /* return value */ 

}; 
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linkblk 



As described in Chapter 11, this is used in lower multiplexor drivers: 



struct linkblk { 
queuet *l_qtop; 
queuet *l_qbot; 
int lindex; 

}; 



/* lowest level write queue of upper stream */ 
/* highest level write queue of lower stream */ 
/* system-unique index for lower stream. */ 
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Appendix B: Message Types 

Eighteen STREAMS message types are defined. The message types differ in 
their intended purposes, their treatment at the Stream head, and in their message 
queueing priority (see Chapter 8). 

STREAMS does not prevent a module or driver from generating any message 
type and sending it in any direction on the Stream. However, established process- 
ing and direction rules should be observed. Stream head processing according to 
message type is fixed, although certain parameters can be altered. 

The message types are described below, classified according to their message 
queueing priority. Ordinary messages are described first, with priority messages 
following. In certain cases, two message types may perform similar functions, 
differing in priority. Message construction is described in Chapter 7. The use of 
the word module will generally imply "module or driver." 
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Ordinary Messages 

These message types are subject to flow control. These are referred to as 
non-priority messages when received at user level. 

MDATA Intended to contain ordinary data. Messages allocated by the 
allocb routine (see Appendix B) are type M DATA by 
default. M DATA messages are generally sent bidirectionally 
on a Stream and their contents can be passed between a pro- 
cess and the Stream head. In the getmsg(2) and putmsg(2) 
system calls, the contents of M DATA message blocks are 
referred to as the data part. Messages composed of multiple 
message blocks will typically have M DATA as the message 
type for all message blocks following the first. 

MPROTO Intended to contain internal control information and associated 
data. The message format is one M PROTO message block 
followed by zero or more M DATA message blocks as shown 
below: The semantics of the M DATA and M PROTO mes- 
sage block are determined by the STREAMS module that 
receives the message. 

The M_PROTO message block will typically contain 
implementation dependent control information. M PROTO 
messages are generally sent bidirectionally on a Stream, and 
their contents can be passed between a process and the Stream 
head. The contents of the first message block of an 
M_PROTO message is generally referred to as the control 
part, and the contents of any following M_DATA message 
blocks are referred to as the data part. In the getmsg(2) and 
putmsg(2) system calls, the control and data parts are passed 
separately. These calls refer to M PROTO messages as non- 
priority messages. 

Note that, although its use is not recommended, the format of 
M PROTO and M PCPROTO (generically PROTO) mes- 
sages sent upstream to the Stream head allows multiple 
PROTO blocks at the beginning of the message, getmsg will 
compact the blocks into a single control part when passing 
them to the user process. 
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Figure B-l: M PROTO and M PCPROTO Message Structure 




M IOCTL Generated by the Stream head in response to an I_STR, and 
certain other, ioctI(2) system calls [see streamio(7)]. When 
one of these ioctls is received from a user process, the Stream 
head uses values from the process and supplied in the call to 
create an M_IOCTL message containing them, and sends the 
message downstream. M_IOCTL messages are intended to 
perform the general ioctl functions of character device drivers, 

The user values are supplied in a structure of the following 
form, provided as an argument to the ioctl call (see I STR in 

streamio) : 

struct strioctl 
{ 

int ic_cmd; 
int ictimout; 
int ic_len; 
char *ic_dp; 

}; 

where ic_cmd is the request (or command) defined by a 
downstream module or driver, icjimout is the time the 



/* downstream request */ 
/* ACK/NAK timeout */ 
/* length of data arg */ 
/* ptr to data arg */ 
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Stream head will wait for acknowledgement to the M_IOCTL 
message before timing out, ic dp is a pointer to an optional 
data argument. On input, icjen contains the length of the 
data argument passed in and, on return from the call, it con- 
tains the length of the data, if any, being returned to the user. 



The form of an MIOCTL message is one MIOCTL mes- 
sage block linked to zero or more M_DATA message blocks. 
STREAMS constructs an M IOCTL message block by plac- 
ing an iocblk structure in its data buffer: 



struct iocblk 
{ 

int ioc_omd; 
ushort ioc uid; 
ushort ioc gid; 
uint ioc id; 
uint ioc_ count; 
int ioc_error; 
int ioc_rval ; 



/* ioctl contend type */ 

/* effective user id number */ 
/* effective group id number */ 
/* ioctl identifier */ 

/* byte count for ioctl data */ 
/* error code */ 

/* return value */ 



The iocblk structure is defined in <sys/stream.h>. ioc_cmd 
corresponds to ic_cmd. ioc_uid and ioc_gid are the effective 
user and group IDs for the user sending the ioctl , and can be 
tested to determine if the user issuing the ioctl call is author- 
ized to do so. ioc_count is the number of data bytes, if any, 
contained in the message and corresponds to ic len . 



ioc id is an identifier generated internally, and is used to 
match each M_IOCTL message sent downstream with a 
response which must be sent upstream to the Stream head. 
The response is contained in an M_IOCACK (positive ack- 
nowledgement) or an M_IOCNAK (negative acknowledge- 
ment) messages. Both these message types have the same 
format as an M IOCTL message and contain an iocblk struc- 
ture in the first block with optional data blocks following. If 
one of these messages reaches the Stream head with an 
identifier which does not match that of the currently- 
outstanding M_IOCTL message, the response message is dis- 
carded. A common means of assuring that the correct 
identifier is returned, is for the replying module to convert the 
M_IOCTL message type into the appropriate response type 
and set ioc_count to 0, if no data is returned. Then, the 
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qreply utility (see Appendix C) is used to send the response to 
the Stream head. 

ioc error holds any return error condition set by a down- 
stream module. If this value is non-zero, it is returned to the 
user in errno. Note that both an MIOCNAK and an 
M_IOCACK may return an error. ioc_rval holds any 
M_IOCACK return value set by a responding module. 

If a user supplies data to be sent downstream, the Stream 
head copies the data, pointed to by ic_dp in the strioctl struc- 
ture, into M DATA message blocks and links the blocks to 
the initial M IOCTL message block. ioc_count is copied 
from ic len. If there is no data, ioccount is zero. 

If a module wants to send data to a user process as part of its 
response, it must construct an MIOCACK message that con- 
tains the data. The first message block of this message con- 
tains the iocblk data structure, with any data stored in one or 
more M_DATA message blocks linked to the first message 
block. The module must set ioc count to the number of data 
bytes sent. On completion of the call, this number is passed 
to the user in icjen. Data associated with an M IOCNAK 
message is not returned to the user process, and is discarded 
by the Stream head. 

The first module or a driver that understands the request con- 
tained in the M_IOCTL acts on it, and generally returns an 
M_IOCACK message. Intermediate modules that do not 
recognize a particular request must pass it on. If a driver 
does not recognize the request, or the receiving module can 
not acknowledge it, an M_IOCNAK message must be 
returned. 

The Stream head waits for the response message and returns 
any information contained in an M IOCACK to the user. 

The Stream head will "time out" if no response is received in 
ic timeout interval. 
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M CTL Generated by modules that wish to send information to a par- 

ticular module or type of module. M CTL messages are typi- 
cally used for inter-module communication, as when adjacent 
STREAMS protocol modules negotiate the terms of their 
interface. An M CTL message cannot be generated by a 
user-level process and is always discarded if passed to the 
Stream head. 

MBREAK Sent to a driver to request that BREAK be transmitted on 
whatever media the driver is controlling. 

The message format is not defined by STREAMS and its use 
is developer dependent. This message may be considered a 
special case of an M CTL message. An M BREAK message 
cannot be generated by a user-level process and is always dis- 
carded if passed to the Stream head. 

M_DELAY Sent to a media driver to request a real-time delay on output. 

The data buffer associated with this message type is expected 
to contain an integer to indicate the number of machine ticks 
of delay desired. M_DELAY messages are typically used to 
prevent transmitted data from exceeding the buffering capa- 
city of slower terminals. 

The message format is not defined by STREAMS and its use 
is developer dependent. Not all media drivers may under- 
stand this message. This message may be considered a spe- 
cial case of an M_CTL message. An M_DELAY message 
cannot be generated by a user-level process and is always dis- 
carded if passed to the Stream head. 

MPASSFP This is used by STREAMS to pass a file pointer from the 

Stream head at one end of a Stream pipe to the Stream head 
at the other end of the same Stream pipe. (A Stream pipe is 
a Stream that is terminated at both ends by a Stream head; 
one end of the Stream can always find the other by following 
the qjiext pointers in the Stream. The means by which such 
a structure is created is not described in this document.) 
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The message is generated as a result of an ISENDFD ioctl 
[see streamio(7)] issued by a process to the sending Stream 
head. STREAMS places the M PASSFP message directly 
on the destination Stream head’s read queue to be retrieved 
by an I RECVFD ioctl [see streamio(7)]. The message is 
placed without passing it through the Stream (i.e., it is not 
seen by any modules or drivers in the Stream). This message 
type should never be present on any queue except the read 
queue of a Stream head. Consequently, modules and drivers 
do not need to recognize this message type, and it can be 
ignored by module and driver developers. 

M_SETOPTS Alters some characteristics of the Stream head. It is gen- 
erated by any downstream module, and is interpreted by the 
Stream head. The data buffer of the message has the follow- 
ing structure: 



struct stroptians 
{ 

short so_f lags ; 
short so readopt; 
ushort so_wroff; 
short so minpsz; 
short so maxpsz; 
ushort so_hiwat ; 
ushort so lowat; 

}; 



/* options to set */ 

/* read option */ 

/* write offset */ 

/* minimum read packet size */ 
/* maximum read packet size */ 

/* read queue high-water mark */ 
/* read queue low-water mark */ 



where so Jiags specifies which options are to be altered, and 
can be any combination of the following: 



□ SO_ALL - Update all options according to the values 
specified in the remaining fields of the stroptions struc- 
ture. 

□ SORE ADOPT - Set the read mode [see read (2)] to 
RNORM (byte stream), RMSGD (message discard), 
or RMSGN (message non-discard) as specified by the 
value of so readopt. 

□ SOWROFF - Direct the Stream head to insert an 
offset specified by sowroff into the first message block 
of all M_DATA messages created as a result of a write 
system call. The same offset is inserted into the first 
M_DATA message block, if any, of all messages 
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created by a putmsg system call. The default offset is 
zero. 

The offset must be less than the maximum message 
buffer size (system dependent) . Under certain cir- 
cumstances, a write offset may not be inserted. A 
module or driver must test that b rptr in the mblk t 
structure is greater than db base in the dblk t struc- 
ture to determine that an offset has been inserted in 
the first message block. 

□ SO_MINPSZ - Change the minimum packet size value 
associated with the Stream head read queue to 
sojninpsz (see qjninpsz in the queue_t structure, in 
Appendix A) . This value is advisory for the module 
immediately below the Stream head. It is intended to 
limit the size of MDATA messages that the module 
should put to the Stream head. There is no intended 
minimum size for other message types. The default 
value in the Stream head is 0. 

□ SO_MAXPSZ - Change the maximum packet size 
value associated with the Stream head read queue to 
sojnaxpsz (see qjnaxpsz in the queue_t structure, in 
Appendix A) . This value is advisory for the module 
immediately below the Stream head. It is intended to 
limit the size of M DATA messages that the module 
should put to the Stream head. There is no intended 
maximum size for other message types. The default 
value in the Stream head is INFPSZ, the maximum 
STREAMS allows. 

□ SO_HIWAT - Change the flow control high water 
mark on the Stream head read queue to the value 
specified in sojiiwat. 

□ SO_LOWAT - Change the flow control low water 
mark (see qjninpsz in the queue t structure, Appendix 
A) on the Stream head read queue to the value 
specified in sojowat. 
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M SIG Sent upstream by modules or drivers to post a signal to a pro- 

cess. When the message reaches the Stream head, the first 
data byte of the message is transformed into a signal, as 
defined in <sys/signal.h>, to the process (es) according to 
the following. 

If the signal is not SIGPOLL and the Stream containing the 
sending module or driver is a controlling TTY, the signal is 
sent to the associated process group. A Stream becomes the 
controlling TTY for its process group if, on open (2), a module 
or driver sets u.ujtyp to point to a (short) "process group 
value." 

If the signal is SIGPOLL, it will be sent only to those 
processes that have explicitly registered to receive the signal 
[see I SETSIG in streamio(7)]. 
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Priority messages are not subject to flow control. 

MPCPROTO This message type has the same format and characteristics as 
the M PROTO message type, except for priority and the fol- 
lowing additional attributes. 

When an M PCPROTO message is placed on a queue, its 
service procedure is always enabled. The Stream head will 
allow only one M_PCPROTO message to be placed in its 
read queue at a time. If an M_PCPROTO message is 
already in the queue when another arrives, the second mes- 
sage is silently discarded and its message blocks freed. 

This message type is intended to allow data and control infor- 
mation to be sent outside the normal flow control constraints. 

The getmsg(2) and putmsg(2) system calls refer to 
M_PCPROTO messages as priority messages. 

M_ERROR This message type is sent upstream by modules or drivers to 
report some downstream error condition. When the message 
reaches the Stream head, the Stream is marked so that all 
subsequent system calls issued to the Stream, excluding 
close (2) and poll (2), will fail with errno set to the first data 
byte of the message. POLLERR is set if the Stream is being 
polled [see poll (2)]. All processes sleeping on a system call to 
the Stream are awakened. An M_FLUSH message with an 
FLUSHRW argument is sent downstream. 

M_HANGUP This message type is sent upstream by a driver to report that 
it can no longer send data upstream. As example, this might 
be due to an error, or to a remote line connection being 
dropped. When the message reaches the Stream head, the 
Stream is marked so that all subsequent write (2) and 
putmsg(2) system calls issued to the Stream will fail and 
return an ENXIO error. Those ioctls that cause messages to 
be sent downstream are also failed. POLLHUP is set if the 
Stream is being polled [see poll (2)]. 

However, subsequent read (2) or getmsg(2) calls to the 
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Stream will not generate an error. These calls will return any 
messages (according to their function) that were on, or in 
transit to, the Stream head read queue before the 
M HANGUP message was received. When all such mes- 
sages have been read, read will return 0, and getmsg will set 
each of its two length fields to 0. 

This message also causes a SIGHUP signal to be sent to the 
process group, if the device is a controlling TTY (see 
MSIG) . 

MIOCACK This message type signals the positive acknowledgement of a 
previous MIOCTL message. The message may contain 
information sent by the receiving module or driver. The 
Stream head returns the information to the user if there is a 
corresponding outstanding M_IOCTL request. The format 
and use of this message type is described further under 
MIOCTL. 

M_IOCNAK This message type signals the negative acknowledgement 
(failure) of a previous M_IOCTL message. When the 
Stream head receives an M_IOCNAK, the outstanding ioctl 
request, if any, will fail. The format and usage of this mes- 
sage type is described further under M_IOCTL. 

MJFLUSH This message type requests all modules and drivers that 

receive it to flush their message queues (discard all messages 
in those queues) as indicated in the message. An MFLUSH 
can originate at the Stream head, or in any module or driver. 
The first byte of the message contains flags that specify one of 
the following actions: 

□ FLUSHR: Flush the read queue of the module. 

□ FLUSH W: Flush the write queue of the module. 

□ FLUSHRW: Flush both the read and the write queue 
of the module. 

Each module passes this message to its neighbor after flushing 
its appropriate queue (s), until the message reaches one of the 
ends of the Stream. 

Drivers are expected to include the following processing for 
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MFLUSH messages. When an MFLUSH message is sent 
downstream through the write queues in a Stream, the driver 
at the Stream end discards it if the message action indicates 
that the read queues in the Stream are not to be flushed (only 
FLUSH W set). If the message indicates that the read 
queues are to be flushed, the driver sets the M FLUSH mes- 
sage flag to FLUSHR, and sends the message up the 
Stream’s read queues. When a flush message is sent up a 
Stream’s read side, the Stream head checks to see if the write 
side of the Stream is to be flushed. If only FLUSHR is set, 
the Stream head discards the message. However, if the write 
side of the Stream is to be flushed, the Stream head sets the 
M_FLUSH flag to FLUSHW and sends the message down 
the Stream’s write side. All modules that enqueue messages 
must identify and process this message type. 

M_PCSIG This message type has the same format and characteristics as 
the M_SIG message type except for priority. 

M START and M STOP 

These messages request devices to start or stop their output. 
They are intended to produce momentary pauses in a device’s 
output, not to turn devices on or off. 

The message format is not defined by STREAMS and its use 
is developer dependent. These messages may be considered 
special cases of an M_CTL message. These messages cannot 
be generated by a user-level process and each is always dis- 
carded if passed to the Stream head. 
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This appendix specifies the set of utilities that STREAMS provides to assist 
development of modules and drivers. There are over 30 utility routines and mac- 
ros. 



The general purpose of the utilities is to perform functions that are commonly 
used in modules and drivers. However, some utilities also provide the required 
interrupt environment. A utility must always be used when operating on a mes- 
sage queue and when accessing the buffer pool. 

The utilities are contained in either the system source file io/stream.c or, if 
they are macros, in <sys/stream.h>. 



NOTE 



The utilities contained in this appendix represent an interface that will be main- 
tained in subsequent versions of UNIX System V. Other than these utilities (also 
see the section titled "Accessible Symbols and Functions" in Appendix D), func- 
tions contained in the STREAMS kernel code may change between versions. 



All structure definitions are contained in Appendix A unless otherwise indicated. 
All routine references are found in this appendix unless otherwise indicated. The 
following definitions are used. 

Blocked A queue that can not be enabled due to flow control (see the 

section titled "Flow Control" in Chapter 6 of the Primer). 

Enable To schedule a queue. 

Free De-allocate a STREAMS storage. 

Message block (bp) 

A triplet consisting of an mblk_t structure, a dblk_t struc- 
ture, and a data buffer. It is referenced by its mblk_t struc- 
ture (see Chapter 7). 

Message (mp) One or more linked message blocks. A message is refer- 
enced by its first message block. 

Message queue Zero or more linked messages associated with a queue 
(queue_t structure) . 
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Queue (q) A queue_t structure. This is generally the same as QUEUE 

in the rest of this document (e.g., see the definitions for 
enable and schedule) . When it appears with "message" in 
certain utility description lines, it means "message queue". 

Schedule Place a queue on the internal linked list of queues which 

will subsequently have their service procedure called by the 
STREAMS scheduler. 

The word module will generally mean "module and/or driver". The phrase 
"next/following module" will generally refer to a module, driver, or Stream head. 
Message queueing priority (see Chapter 8 and Appendix B) can be ordinary or 
Priority (to avoid "priority priority") . 
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The utilities are described below. A summary table is contained at the end of 
this appendix. 



adjmsg — trim bytes in a message 

int adjmsg (mp, len) 
mblkt *mp; 
int len; 

adjmsg trims bytes from either the head or tail of the message specified by mp. If 
len is greater than zero, it removes len bytes from the beginning of mp. If len is 
less than zero, it removes ( -)len bytes from the end of mp. If len is zero, adjmsg 
does nothing, adjmsg only trims bytes across message blocks of the same type. It 
will fail if mp points to a message containing fewer than len bytes of similar type 
at the message position indicated, adjmsg returns 1 on success, and 0 on failure. 



allocb — allocate a message block 

mblk t * allocb (size, pri) 
int size, pri; 

allocb returns a pointer to a message block of type M_DATA, in which the data 
buffer contains at least size bytes, pri indicates the priority of the allocation 
request, and can have the values BPRI LO, BPRI MED or BPRI HI (see the 
section titled "Buffer Allocation Priority" in this appendix). If a block can not be 
allocated as requested, allocb returns a NULL pointer. 



backq — get pointer to the queue behind a given queue 

queuet * backq (q) 
queuet *q; 

backq returns a pointer to the queue behind a given queue. That is, it returns a 
pointer to the queue whose qjiext (see queue t structure) pointer is q. If no such 
queue exists (as when q is at a Stream end) , backq returns NULL. 
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bufcall — recover from failure of allocb 

int bufcall (size, pri, func, arg) 
int (*func)(); 
int size, pri; 
long arg; 

bufcall is provided to assist in the event of a block allocation failure. If allocb 
returns NULL, indicating a message block is not currently available, bufcall may 
be invoked. 

bufcall arranges for ( *func ) (arg) to be called when a buffer of size bytes at pri 
priority (see the section titled "Buffer Allocation Priority" below) is available. 
When func is called, it has no user context. It cannot reference the u area and 
must return without sleeping, bufcall does not guarantee that the desired buffer 
will be available when func is called since interrupt processing may acquire it. 

bufcall returns 1 on success, indicating that the request has been successfully 
recorded, or 0 on failure. On a failure return, func will never be called. A failure 
indicates a (temporary) inability to allocate required internal data structures. 



canput — test for room in a queue 

int canput (q) 
queue t *q; 

canput determines if there is room left in a message queue. If q does not have a 
service procedure, canput will search further in the same direction in the Stream 
until it finds a queue containing a service procedure (this is the first queue on 
which the passed message can actually be enqueued) . If such a queue cannot be 
found, the search terminates on the queue at the end of the Stream, canput tests 
the queue found by the search. If the message queue in this queue is not full (see 
the section titled "Flow Control" in Chapter 6 of the Primer ), canput returns 1. 
This return indicates that a message can be put to queue q. If the message queue 
is full, canput returns 0. In this case, the caller is generally referred to as 
blocked. 
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copyb — copy a message block 

mblkt * copyb (bp) 
mblkt *bp; 

copyb copies the contents of the message block pointed at by bp into a newly- 
allocated message block of at least the same size, copyb allocates a new block by 
calling allocb with pri set to BPRIMED (see the section titled "Buffer Allocation 
Priority", below). All data between the brptr and b_wptr pointers of a message 
block are copied to the new block, and these pointers in the new block are given 
the same offset values they had in the original message block. On successful com- 
pletion, copyb returns a pointer to the new message block containing the copied 
data. Otherwise, it returns a NULL pointer. 



copymsg — copy a message 

mblk t *copymsg(mp) 
mblk t *mp; 

copymsg uses copyb to copy the message blocks contained in the message pointed 
at by mp to newly-allocated message blocks, and links the new message blocks to 
form the new message. On successful completion, copymsg returns a pointer to 
the new message. Otherwise, it returns a NULL pointer. 



datamsg — test whether message is a data message 

^define datamsg (mp) ... 

The datamsg macro returns TRUE if mp (declared as mblk_t *mp) points to a 
data type message. In this case, types M DATA, M PROTO, or M PCPROTO 
(see Appendix B) . If mp points to any other message type, datamsg returns 
FALSE. 
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dupb — duplicate a message block descriptor 

mblkt * dupb (bp) 
mblkt *bp; 

dupb duplicates the message block descriptor (mblk_t structure) pointed at by bp 
by copying it into a newly allocated message block descriptor. A message block is 
formed with the new message block descriptor pointing to the same data block as 
the original descriptor. The reference count in the data block descriptor (dblk t 
structure) is incremented, dupb does not copy the data buffer, only the message 
block descriptor. 

On successful completion, dupb returns a pointer to the new message block. If 
dupb cannot allocate a new message block descriptor, it returns NULL. 

This routine allows message blocks that exist on different queues to reference the 
same data block. In general, if the contents of a message block with a reference 
count greater than 1 are to be modified, copyb should be used to create a new 
message block and only the new message block should be modified. This insures 
that other references to the original message block are not invalidated by 
unwanted changes. 



dupmsg — duplicate a message 

mblk t *dupmsg(mp) 
mblk t *mp; 

dupmsg calls dupb to duplicate the message pointed at by mp , by copying all indi- 
vidual message block descriptors, and then linking the new message blocks to 
form the new message, dupmsg does not copy data buffers, only message block 
descriptors. On successful completion, dupmsg returns a pointer to the new mes- 
sage. Otherwise, it returns NULL. 



enableok — re-allow a queue to be scheduled for service 
^define enableok (q) ... 

The enableok macro cancels the effect of an earlier noenable on the same queue q 
(declared as queue_t *q) . It allows a queue to be scheduled for service that had 
previously been excluded from queue service by a call to noenable. 
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flushq — flush a queue 

int flushq (q, flag) 
queuet *q; 
int flag; 

flushq removes messages from the message queue in queue q and frees them, using 
freemsg. If flag is set to FLUSHDATA, then flushq discards all MDATA, 
M_PROTO, and M_PCPROTO messages (see datamsg), but leaves all other mes- 
sages on the queue. If flag is set to FLUSHALL, all messages are removed from 
the message queue and freed. FLUSHALL and FLUSHDATA are defined in 
<sys/stream.h>. 

If a queue behind q is blocked, flushq may enable the blocked queue, as described 

in putq. 



freeb — free a message block 

int freeb (bp) 
mblkt *bp; 

freeb will free (de-allocate) the message block descriptor pointed at by bp , and 
free the corresponding data block if the reference count (see dupb) in the data 
block descriptor (dblk t structure) is equal to 1 . If the reference count is greater 
than 1 , freeb will not free the data block, but will decrement the reference count. 



freemsg — free all message blocks in a message 

int freemsg (mp) 
mblk t *mp; 

freemsg uses freeb to free all message blocks and their corresponding data blocks 
for the message pointed at by mp. 
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getq — get a message from a queue 

mblkt *getq(q) 
queuet *q; 

getq gets the next available message from the queue pointed at by q. getq returns 
a pointer to the message and removes that message from the queue. If no mes- 
sage is queued, getq returns NULL. 

getq, and certain other utility routines, affect flow control in the Stream as fol- 
lows: If getq returns NULL, the queue is internally marked so that the next time 
a message is placed on it, it will be scheduled for service (enabled, see qenable) . 
Also, if the data in the enqueued messages in the queue drops below the low- 
water mark, qjowat , and a queue behind the current queue had previously 
attempted to place a message in the queue and failed (i.e., was blocked, see can- 
put), then the queue behind the current queue is scheduled for service (see the 
section titled "Flow Control" in Chapter 6 of the Primer). 



insq — put a message at a specific place in a queue 

int insq(q, emp, nmp) 

queue t *q; 

mblk t *emp, *nmp; 

insq places the message pointed at by nmp in the message queue contained in the 
queue pointed at by q immediately before the already-enqueued message pointed 
at by emp. If emp is NULL, the message is placed at the end of the queue. If 
emp is non-NULL, it must point to a message that exists on the queue q , or a 
system panic could result. 

Note that the message is placed where indicated, without consideration of mes- 
sage queueing priority. The queue will be scheduled in accordance with the rules 
described in putq for ordinary priority messages. 
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linkb — concatenate two messages into one 

int linkb (mpl, mp2) 
mblkt *mpl; 
mblkt *mp2; 

linkb puts the message pointed at by mp2 at the tail of the message pointed at by 
mpl. 



msgdsize — get the number of data bytes in a message 

int msgdsize (mp) 
mblk t *mp; 

msgdsize returns the number of bytes of data in the message pointed at by mp. 
Only bytes included in data blocks of type M DATA are included in the total. 



noenable — prevent a queue from being scheduled 
#define noenable(q) .... 

The noenable macro prevents the queue q (declared as queuejt *q) from being 
scheduled for service by putq or putbq when these routines enqueue an ordinary 
priority message, or by insq when it enqueues any message, noenable does not 
prevent the scheduling of queues when a Priority message is enqueued, unless it is 
enqueued by insq. 



OTHERQ — get pointer to the mate queue 
^define OTHERQ(q) ... 

The OTHERQ macro returns a pointer to the mate queue of q (declared as 
queue_t *q). If q is the read queue for the module, it returns a pointer to the 
module’s write queue. If q is the write queue for the module, it returns a pointer 
to the read queue. 
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pullupmsg — concatenate bytes in a message 

int * pullupmsg (mp, len) 
mblkt *mp; 
int len; 

pullupmsg concatenates and aligns the first len data bytes of the passed message 
into a single, contiguous message block. Proper alignment is hardware-dependent. 
To perform its function, pullupmsg allocates a new message block by calling allocb 
with pri set to BPRI_MED (see the section titled "Buffer Allocation Priority" 
below), pullupmsg only concatenates across message blocks of similar type. It 
will fail if mp points to a message of less than len bytes of similar type. A len 
value of -1 requests a pull-up of all the like-type blocks in the beginning of the 
message pointed at by mp. 

At completion of concatenation, pullupmsg replaces mp with a pointer to the new 
message block, so that mp still points to the same message block at the end of the 
operation. However, the contents of the message block may have been altered. 

On success, pullupmsg returns 1. On failure, it returns 0. 



putbq — return a message to the beginning of a queue 

int putbq (q, bp) 
queue t *q; 
mblk t *bp 

putbq puts the message pointed at by bp at the beginning of the queue pointed at 
by q , in a position in accordance with the message’s type. Priority messages are 
placed at the head of the queue, and ordinary messages are placed after all Prior- 
ity messages, but before all other ordinary messages. The queue will be scheduled 
in accordance with the same rules described in putq. This utility is typically used 
to replace a message on a queue from which it was just removed. 
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putctl — put a control message 

int putctl (q, type) 
queuet *q; 
int type; 

putctl creates a control (not data, see datamsg, above) message of type type , and 
calls the put procedure in the queue pointed at by q , with a pointer to the created 
message as an argument, putctl allocates new blocks by calling allocb with pri set 
to BPRI HI (see the section titled "Buffer Allocation Priority" below). On suc- 
cessful completion, putctl returns 1 . It returns 0 if it cannot allocate a message 
block, or if type MDATA, MPROTO or MPCPROTO was specified. 



putctl 1 — put a control message with a one-byte parameter 

int putctlKq, type, p) 
queue t *q; 
int type; 
int p; 

putctll creates a control (not data, see datamsg, above) message of type type with 
a one-byte parameter p, and calls the put procedure in the queue pointed at by q , 
with a pointer to the created message as an argument, putctll allocates new 
blocks by calling allocb with pri set to BPRI_HI (see the section titled "Buffer 
Allocation Priority" below). On successful completion, putctll returns 1. It 
returns 0 if it cannot allocate a message block, or if type M DATA, M PROTO 
or M PCPROTO was specified. 



putnext — put a message to the next queue 

^define putnext (q, mp) ... 

The putnext macro calls the put procedure of the next queue in a Stream, and 
passes it a message pointer as an argument. The parameters must be declared as 
queue_t *q and niblkjt *mp. q is the calling queue (not the next queue) and mp 
is the message to be passed, putnext is the typical means of passing messages to 
the next queue in a Stream. 
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putq — put a message on a queue 

int putq(q, bp) 
queuet *q; 
mblkt *bp; 

putq puts the message pointed at by bp on the message queue contained in the 
queue pointed at by q and enables that queue, putq queues messages appropri- 
ately by type (i.e., message queueing priority, see Chapter 8). 

putq will always enable the queue when a Priority message is queued, putq will 
enable the queue when an ordinary message is queued if the following condition is 
set, and enabling is not inhibited by noenable: The condition is set if the module 
has just been pushed [see I_PUSH in streamio(7)], or if no message was queued 
on the last getq call and no message has been queued since. 

putq is intended to be used from the put procedure in the same queue in which 
the message will be queued. A module should not call putq directly to pass mes- 
sages to a neighboring module, putq may be used as the qi _putpQ put procedure 
value in either or both of a module’s qinit structures. This effectively bypasses 
any put procedure processing and uses only the module’s service procedure (s). 



qenable — enable a queue 
int qenable(q) queue t *q; 

int putq(q, bp) 
queue t *q; 
mblk t *bp; 

qenable places the queue pointed at by q on the linked list of queues that are 
ready to be called by the STREAMS scheduler (see the definition for "Schedule" 
above, and the section titled "Put and Service Procedures" in Chapter 5 of the Pri- 
mer). 
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qreply — send a message on a stream in the reverse direction 

int qreply (q, bp) 
queuet *q; 
mblkt *bp; 

qreply sends the message pointed at by bp up (or down) the Stream in the reverse 
direction from the queue pointed at by q. This is done by locating the partner of 
q (see OTHERQ, below), and then calling the put procedure of that queue’s 
neighbor (as in putnext) . qreply is typically used to send back a response 
(M IOCACK or M IOCNAK message) to an M IOCTL message (see Appendix 
B). 



qsize — find the number of messages on a queue 

int qsize (q) 
queue t *q; 

qsize returns the number of messages present in queue q. If there are no mes- 
sages on the queue, qsize returns 0. 



RD — get pointer to the read queue 
#define RD(q) ... 

The RD macro accepts a write queue pointer, q (declared as queuejt *q), as an 
argument and returns a pointer to the read queue for the same module. 

rmvb — remove a message block from a message 



mblk t *rmvb(mp, bp) 
mblk t *mp; 
mblk t *bp; 

rmvb removes the message block pointed at by bp from the message pointed at by 
m/7, and then restores the linkage of the message blocks remaining in the message, 
rmvb does not free the removed message block, rmvb returns a pointer to the 
head of the resulting message. If bp is not contained in mp , rmvb returns a -1. If 
there are no message blocks in the resulting message, rmvb returns a NULL 
pointer. 
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rmvq — remove a message from a queue 

int rmvq(q, mp) 
queue t *q; 
mblk t *mp; 

rmvq removes the message pointed at by mp from the message queue in the queue 
pointed at by q , and then restores the linkage of the messages remaining on the 
queue. If mp does not point to a message that is present on the queue q , a system 
panic could result. 



splstr — set processor level 

int splstr 0 

splstr increases the system processor level to block interrupts at a level appropri- 
ate for STREAMS modules when those modules are executing critical portions of 
their code, splstr returns the processor level at the time of its invocation. Module 
developers are expected to use the standard kernel function splx(s), where s is the 
integer value returned by splstr, to restore the processor level to its previous value 
after the critical portions of code are passed. 



strlog — submit messages for logging 

int strlog(mid, sid, level, flags, fmt, argl, ...) 

short mid, sid; 

char level; 

ushort flags; 

char *fmt; 

unsigned argl; 

strlog submits messages containing specified information to the log (7) driver. 
Required definitions are contained in <sys/strlog.h> and <sys/log.h>. mid is 
the STREAMS module id number for the module or driver submitting the log 
message, sid is an internal sub-id number usually used to identify a particular 
minor device of a driver, level is a tracing level that allows selective screening of 
messages from the tracer, flags are any combination of SL_ERROR (the mes- 
sage is for the error logger), SL_TRACE (the message is for the tracer), 
SL_FATAL (advisory notification of a fatal error), and SL NOTIFY (request 
that a copy of the message be mailed to the system administrator) . fmt is a 
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printf(3S) style format string, except that %s, %e, %E, %g, and %G conversion 
specifications are not handled. Up to NLOGARGS numeric or character argu- 
ments can be provided. (See Chapter 6 of the Primer , and log(7).) 



testb — check for an available buffer 

int testb (size, pri) 
int size, pri; 

testb checks for the availability of a message buffer of size size at priority pri (see 
the section titled "Buffer Allocation Priority", below) without actually retrieving 
the buffer, testb returns 1 if the buffer is available, and 0 if no buffer is available. 
A successful return value from testb does not guarantee that a subsequent allocb 
call will succeed (e.g., in the case of an interrupt routine taking buffers). 



unlinkb — remove a message block from the head of a message 

mblkt *unlinkb(mp) 
mblkt *mp; 

unlinkb removes the first message block pointed at by mp and returns a pointer to 
the head of the resulting message, unlinkb returns a NULL pointer if there are 
no more message blocks in the message. 



WR — get pointer to the write queue 
#define WR(q) ... 

The WR macro accepts a read queue pointer, q (declared as queue_t *q), as an 
argument and returns a pointer to the write queue for the same module. 
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STREAMS buffers are normally allocated with allocb, described above. An 
associated set of allocation priorities has been established, which are also used in 
other utility routines: 

BPRI_LO Low priority. At this priority, allocb may fail even though the 
requested buffer size is available. This priority is used by the 
Stream head write routine to hold data associated with user calls. 

BPRIMED Medium priority. This priority is typically used for normal data 
and control block allocation. As above, allocb may fail at this 
priority even though a buffer of the requested size is available. 
However, for a given block size, an BPRI_LO allocb call will fail 
before a BPRI MED allocb call. 

BPRIHI High priority. This priority is typically used only for critical con- 
trol message allocations. Calls to allocb will succeed if a buffer of 
the appropriate size is available. Developers should exercise res- 
traint in use of BPRI HI allocation requests. 



The values BPRI LO, BPRI_MED,and BPRI HI are defined in 
<sys/stream.h>. 

STREAMS does not guarantee successful buffer allocation— any set of 
resources can be exhausted under the right conditions. The bufcall function will 
help modules recover from buffer allocation failures, but it does not guarantee 
that the resources will ever be available. Developers should be aware of this when 
implementing modules. 
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ROUTINE 


DESCRIPTION 


adjmsg 


trim bytes in a message 


allocb 


allocate a message block 


backq 


get pointer to the queue behind a given queue 


bufcall 


recover from failure of allocb 


canput 


test for room in a queue 


copyb 


copy a message block 


copymsg 


copy a message 


datamsg 


test whether message is a data message 


dupb 


duplicate a message block descriptor 


dupmsg 


duplicate a message 


enableok 


re-allow a queue to be scheduled for service 


flushq 


flush a queue 


freeb 


free a message block 


freemsg 


free all message blocks in a message 


getq 


get a message from a queue 


insq 


put a message at a specific place in a queue 


linkb 


concatenate two messages into one 


msgdsize 


get the number of data bytes in a message 


noenable 


prevent a queue from being scheduled 


OTHERQ 


get pointer to the mate queue 


pullupmsg 


concatenate bytes in a message 


putbq 


return a message to the beginning of a queue 


putctl 


put a control message 


putctll 


put a control message with a one-byte parameter 


putnext 


put a message to the next queue 


Putq 


put a message on a queue 


qenable 


enable a queue 


qreply 


send a message on a stream in the reverse direction 


qsize 


find the number of messages on a queue 


RD 


get pointer to the read queue 


rmvb 


remove a message block from a message 


rmvq 


remove a message from a queue 


splstr 


set processor level 


strlog 


submit messages for logging 


testb 


check for an available buffer 


unlinkb 


remove a message block from the head of a message 


WR 


get pointer to the write queue 
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This appendix summarizes STREAMS module and driver design guidelines 
and rules presented in previous chapters. Additional rules that developers must 
observe are included. Where appropriate, the section of this document containing 
detailed information is named. The end of the appendix contains a brief descrip- 
tion of error and trace logging facilities. 

Unless otherwise noted, "module" implies "modules and drivers". 



General Rules 

The following are general rules that developers should follow when writing 
modules. 

1 . Modules cannot access information in the u_area of a process. Modules 
are not associated with any process, and therefore have no concept of pro- 
cess or user context. 

The capability to pass u_area information upstream using messages has 
been provided where required. This can be done in MIOCTL handling 
(see Chapter 9 and Appendix B) . A module can send error codes 
upstream in a M_IOCACK or M_IOCNAK message, where they will be 
placed in u error by the Stream head. Return values may also be sent 
upstream in a M_IOCACK message, and will be placed in u_rvall. 
Information can also be passed to, the uarea via a M_ERROR message 
(see Chapter 10 and Appendix B). The Stream head will recognize this 
message type and inform the next system call that an error has occurred 
downstream by setting u_error. Note that in both instances, the down- 
stream module cannot access the u area, but it informs the Stream head 
to do so. 

2. In general, modules should not require the data in an M_DATA message 
to follow a particular format, such as a specific alignment. This makes it 
easier to arbitrarily push modules on top of each other in a sensible 
fashion. Not following this rule may limit module re-usability (the abil- 
ity to use the module in multiple applications) . 

3. Every module must process an M_FLUSH message according to the 
value of the argument passed in the message. (See Chapters 8 and 9, 
and Appendix B.) 
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4. A module should not change the contents of a data block whose reference 
count is greater than 1 (see dupmsg in Appendix C) because other 
modules that have references to the block may not want the data 
changed. To avoid problems, it is recommended that the module copy the 
data to a new block and then change the new one. 

5. Modules should only manipulate message queues and manage buffers 
with the routines provided for those purpose, (see Appendix C) . 

6. Filter modules pushed between a service user and a service provider (see 
Chapter 12) may not alter the contents of the M PROTO or 
M_PCPROTO block in messages. The contents of the data blocks may 
be manipulated, but the message boundaries must be preserved. 



System Calls 

These rules pertain to module and drivers as noted. 

1 . open and close routines may sleep, but the sleep must return to the rou- 
tine in the event of a signal. That is, if they sleep, they must be at prior- 
ity <= PZERO, or with PCATCH set in the sleep priority. 

2. The open routine must return >= zero on success or OPENFAIL if it 
fails. This ensures that a failure will be reported to the user process. 
errno may be set on failure. However, if the open routine returns OPEN- 
FAIL and errno is not set, STREAMS will automatically set errno to 
ENXIO. 

3 . If a module or driver recognizes and acts on an MIOCTL message, it 
must reply by sending a M_IOCACK message upstream. A unique id is 
associated with each M IOCTL, and the M IOCACK or M IOCNAK 
message must contain the id of the M IOCTL it is acknowledging. 

4. A module (not a driver) must pass on any M IOCTL message it does not 
recognize (see Appendix B). If an unrecognized M IOCTL reaches a 
driver, the driver must reply by sending a MIOCNAK message 
upstream. 
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Data Structures 

Only the contents of q_ptr, qjninpsz, q maxpsz, q hiwat , and q lowat. in a 
queue t structure may be altered. The latter four quantities are set when the 
module or driver is opened, but may be modified subsequently. 

As described in Appendix E, every module and driver is configured in with 
the address of a streamtab structure (see Chapter 5) . For a driver, a pointer to 
its streamtab is included in cdevsw. For a module, a pointer to its streamtab is 
included in fmodsw. 



Header Files 

The following header files are generally required in modules and drivers: 

types.h contains type definitions used in the STREAMS header files 

stream.h contains required structure and constant definitions 

stropts.h primarily for users, but contains definitions of the arguments to 
the M_FLUSH message type also required by modules 



One or more of the header files described below may also be included (also 
see the following section). No standard UNIX system header files should be 
included except as described in the following section. The intent is to prevent 
attempts to access data that cannot or should not be accessed. 



errno.h defines various system error conditions, and is needed if errors 

are to be returned upstream to the user 

sysmacros.h contains miscellaneous system macro definitions 

param.b defines various system parameters, particularly the value of the 
PCATCH sleep flag 

signal.h defines the system signal values, and should be used if signals 

are to be processed or sent upstream 
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file.h defines the file open flags, and is needed if ONDELAY is 

interpreted 



Accessible Symbols and Functions 



The following lists the only symbols and functions that modules or drivers 
may refer to (in addition to those defined by STREAMS), if hardware and 
UNIX system release independence is to be maintained. Use of symbols not 
listed here is unsupported. 



user.h (from open/close procedures only) 



struct proc *u_procp 
short *u_ttyp 
char u_error 
ushort u uid 
ushort ujgid 
ushort u ruid 
ushort u rgid 



process structure pointer 
tty group ID pointer 
system call error number 
effective user ID 
effective group ID 
real user ID 
real group ID 



■ proc.h (from open/close procedures only) 

short p_pid process ID 

short p_pgrp process group ID 



■ functions accessible from open/close procedures only 

fig — sleep (chan, pri) sleep until wakeup 

delay (ticks) delay for a specified time 



■ universally accessible functions 

bcopy(from, to, nbytes) 
bzero (buffer, nbytes) 
t = max (a, b) 
t — min (a, b) 
mem=malloc(mp, size) 
mfree(mp, size, i) 
mapinit(mp, mapsize) 
addr = vtop(vaddr, NULL) 
printf (format, ...) 
cmn_err (level, ...) 
s = spl«() 

id = timeout (func, arg, ticks) 



copy data quickly 

zero data quickly 

return max of args 

return min of args 

allocate memory space 

de-allocate memory space 

initialize map structure 

translate from virtual to physical address 

print message 

print message and optional panic 
set priority level 
schedule event 
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untimeout (id) 


cancel event 


wakeup(chan) 


wake up sleeper 


■ sysmacros.h 




t = major (dev) 


return major device 


t = minor (dev) 


return minor device 


■ systm.h 




time_t lbolt 


clock ticks since boot in HZ 


time_t time 


seconds since epoch 


■ param.h 




PZERO 


zero sleep priority 


PCATCH 


catch signal sleep flag 


HZ 


clock ticks per second 


NULL 


0 


■ types.h 




devt 


combined major/minor device 


time t 


time counter 



All data elements are software read-only except: 

u error - may be set on a failure return of open 
u ttyp - may be set in open to create a controlling tty 



Rules for Put and Service Procedures 

To ensure proper data flow between modules, the following rules should be 
observed in put and service procedures. The following rules pertain to put pro- 
cedures. 

1 . A put procedure must not sleep. 

2. Each QUEUE must define a put procedure in its qinit (see Appendix A) 
structure for passing messages between modules. 

3. A put procedure must use the putq (see Appendix C) utility to enqueue a 
message on its own message queue. This is necessary to ensure that the 
various fields of the queue_t structure are maintained consistently. 
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4. When passing messages to a neighbor module, a module may not call 
putq directly, but must call its neighbor’s put procedure (see putnext in 
Appendix C) . Note that this rule is distinct from the one above it. The 
previous rule states that a module must call putq to place messages on its 
own message queue, whereas this rule states that a module must not call 
putq directly to place messages on a neighbor’s queue. 

However, the qjqinfo structure that points to a module’s put procedure 
may point to putq (i.e. putq is used as the put procedure for that module). 
When a module calls a neighbor’s put procedure that is defined in this 
manner, it will be calling putq indirectly. If any module uses putq as its 
put procedure in this manner, the module must define a service pro- 
cedure. Otherwise, no messages will ever be sent to the next module. 
Also, because putq does not process M_FLUSH messages, any module 
that uses putq as its put procedure must define a service procedure to pro- 
cess M FLUSH messages. 

5. The put procedure of a QUEUE with no service procedure must call the 
put procedure of the next QUEUE directly, if a message is to be passed 
to that QUEUE. If flow control is desired, a service procedure must be 
provided. 

Service procedures must observe the following rules: 

1 . A service procedure must not sleep. 

2. The service procedure must use getq to remove a message from its mes- 
sage queue, so that the flow control mechanism is maintained. 

3 . The service procedure should process all messages on its message queue. 
The only exception is if the Stream ahead is blocked (i.e., canput fails, 
see Appendix C) . Adherence to this rule is the only guarantee that 
STREAMS will enable (schedule for execution) the service procedure 
when necessary, and that the flow control mechanism will not fail. 

If a service procedure exits for any other reason (e.g., buffer allocation 
failure), it must take explicit steps to assure it will be re-enabled. 
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4. The service procedure must follow the steps below for each message that 
it processes. STREAMS flow control relies on strict adherence to these 
steps. 

Step 1 : Remove the next message from the message queue using getq. It 

is possible that the service procedure could be called when no 
messages exist on the queue, so the service procedure should 
never assume that there is a message on its message queue. If 
there is no message, return. 

Step 2: If all the following conditions are met: 

□ canput fails and 

□ the message type is not a priority type (see Appendix B) 
and 

□ the message is to be put on the next QUEUE. 

then, continue at Step 3. Otherwise, continue at Step 4. 

Step 3: The message must be replaced on the head of the message queue 

from which it was removed using putbq (see Appendix C) . Fol- 
lowing this, the service procedure is exited. The service pro- 
cedure should not be re-enabled at this point. It will be automat- 
ically back-enabled by flow control. 

Step 4: If all the conditions of Step 2 are not met, the message should 

not be returned to the queue. It should be processed as neces- 
sary. Then, return to Step 1 . 



Error and Trace Logging 

STREAMS error and trace loggers are provided for debugging and for 
administering modules and driver. Chapter 6 of the STREAMS Primer contains 
a description of this facility which consists of log (7), strace(lM), strclean(lM) 
strerr(lM) and the strlog function described in Appendix C. 
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This appendix contains information about configuring STREAMS modules 
and drivers into UNIX System V Release 3 on the AT&T 3B2 Computer. The 
information is incremental and presumes the reader is familiar with the 
configuration mechanism, which may vary on different processors. An example of 
how to configure a driver and a module is included. 

This appendix also includes a list of STREAMS system tunable parameters 
and system error messages. 



Configuring STREAMS Modules and Drivers 

Each character device that is configured into a UNIX system results in an 
entry being placed in the kernel cdevsw table. Entries for STREAMS drivers are 
also placed in this table. However, because system calls to STREAMS drivers 
must be processed by the STREAMS routines, the configuration mechanism dis- 
tinguishes between STREAMS drivers and character device drivers in their asso- 
ciated cdevsw entries. 

The distinction is contained in the dstr field which was added to the cdevsw 
structure for this purpose, d str provides the appropriate single entry point for all 
system calls on STREAMS files, as shown below: 

extern struct cdevsw { 



struct streamtab *d_str; 

} cdevsw [ ] ; 

The configuration mechanism forms the d str entry name by appending the string 
"info" to the STREAMS driver prefix. The "info" entry is a pointer to a stream- 
tab structure (see Appendix A) that contains pointers to the qinit structures for 
the read and write QUEUEs of the driver. The driver must contain the external 
definition: 

struct streamtab prefix info = { ... 

If the djtr entry contains a non-NULL pointer, the operating system will recog- 
nize the device as a STREAMS driver and will call the appropriate STREAMS 
routine. If the entry is NULL, a character I/O device cdevsw interface is used. 
Note that only streamtab must be externally defined in STREAMS drivers and 
modules, streamtab is used to identify the appropriate open, close, put, service, 
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and administration routines. These driver/module routines should generally be 
declared static. 

The configuration mechanism supports various combinations of block, charac- 
ter, STREAMS devices and STREAMS modules (see below) . For example, it is 
possible to identify a device as a block and STREAMS device, and entries will be 
inserted in the appropriate system switch tables. On the 3B2 Computer, a device 
cannot be both a character and STREAMS device. 

When a STREAMS module is configured, an fmodsw table entry is generated 
by the configuration mechanism, fmodsw contains the following: 

#define 5MNAMESZ 8 

extern struct fmodsw { 

char f_name[EMNAMESZ+1] ; 
struct streamtab *f str; 

} fmodsw[ ]; 

f name is the name of the module, used in STREAMS-related ioctl calls. 
f_str is similar to the djtr entry in the cdevsw table. It is a pointer to a stream- 
tab structure which contains pointers to the qinit structures for the read and write 
QUEUES of this STREAMS module (as in STREAMS drivers) . The module 
must contain the external definition: 

struct streamtab prefix±n£o = { . . . 



3B2 Computer Configuration Mechanism 

The 3B2 Computer configuration mechanism differentiates STREAMS 
devices from character devices by a special type in the flag field of master files 
contained in /etc/master .d [see master (4)]. The c flag specifies a non-STREAMS 
character I/O device driver. The f flag specifies that the associated cdevsw entry 
will be a STREAMS driver. The special file (node) that identifies the 
STREAMS driver must be a character special file, as is the file for a character 
device driver, because the system call entry point for STREAMS drivers is also 
the cdevsw table 

STREAMS modules are identified by an m in the flag field of master files 
contained in /etc/master. d and the configuration mechanism creates an associated 
fmodsw table entry for all such modules. 
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NOTE 



Any combination of block, STREAMS drivers and STREAMS module may be 
specified. However, on the 3B2 Computer, it is illegal to specify a STREAMS 
device or module with a character device. 



Configuration Examples 

This section contains examples of configuring the following STREAMS driver 
and module: 

loop the STREAMS loop-around software driver of Chapter 10 
crmod the conversion module of Chapter 7 

To configure the STREAMS software (pseudo-device) driver, loop , and 
assign values to the driver extern variables, the following must appear in the file 
/etc/master.d/Ioop [see master (4)]: 

* LOOP - STREAMS loop around software driver 

* 

*FLAG #VEC PREFIX SOFT #DEV IPL DEPENDENCIES/VARIABLES 

fs - loop 62 

loop_loop[NLP] (%i%l) 
loop_cnt (%i) ={NLP} 

$$$ 

NLP = 2 

The flag field is set to "fs" which signifies that it is a STREAMS driver and a 
software driver. The prefix "loop" requires that the streamtab structure for the 
driver be defined as loopinfo. "62" is an unused, but otherwise arbitrary, software 
driver major number. If this field contained an unused software driver major 
number would be assigned by drivinstall(lM). 

To configure the STREAMS module crmod , the following must appear in the 
file /etc/master.d/crmod: 

* CRMOD stream conversion module 

* 

♦FLAG #VEC PREFIX SOFT #DEV IPL DEPENDENCIES/VARIABLES 

m - crmd 

The flag field is set to "m", which signifies that it is a STREAMS module. 
The prefix "crmd" (cannot exceed four characters) requires that the streamtab 
structure for the module be defined as crmdinfo . The configuration mechanism 
uses the name of the master.d file ( crmod in this case) to create the module name 
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field ( fjiame ) of the associated fmodsw entry. The prefix and module name can 
be different. 

mkboot(lM) should be run on the corresponding object files in the appropri- 
ate directories for these master files. Also, if it is desired to have these objects 
loaded at boot time, then the file /etc/system must contain the following entries: 

include: loop 

INCLUDE: CRMOD 

Neither of the above examples are hardware drivers. Configuring a 
STREAMS hardware driver is a similar to configuring a character I/O hardware 
driver: The major device number is the hardware board address and no 
INCLUDE is required. 



Tunable Parameters 



Certain system parameters referenced by STREAMS are configurable when 
building a new operating system (see the System Administrator’s Guide for fur- 
ther details). This can be done by including the appropriate entry in the kernel 
master file, "queues" refers to queue_t structures. These parameters are: 



NQUEUE 



NSTREAM 

NBLK4096 



Total number of queues that may be allocated at one time by 
the system. Queues are allocated in pairs. Each STREAMS 
driver, Stream head and pushable module requires a pair of 
queues. A minimal Stream contains 4 queues (two for the 
Stream head, two for the driver). 

Total number of Streams that may be open at one time in a 
system. 

Total number of 4096 byte data blocks available for 
STREAMS operations. The pool of data blocks is a system- 
wide resource, so enough blocks must be configured to satisfy 
all Streams. 



NBLK2048 Total number of 2048 byte data blocks available for 

STREAMS operations. 

NBLK1024 Total number of 1024 byte data blocks available for 

STREAMS operations. 
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NBLK512 

NBLK256 

NBLK128 

NBLK64 

NBLK16 

NBLK4 

NMUXLINK 

NSTREVENT 

MAXSEPGCNT 

NSTRPUSH 

STRMSGSZ 



Total number of 512 byte data blocks available for 
STREAMS operations. 

Total number of 256 byte data blocks available for 
STREAMS operations. 

Total number of 128 byte data blocks available for 
STREAMS operations. 

Total number of 64 byte data blocks available for STREAMS 
operations. 

Total number of 16 byte data blocks available for STREAMS 
operations. 

Total number of 4 byte data blocks available for STREAMS 
operations. 

Total number of Streams in system that can be linked as 
lower Streams to multiplexor drivers [by an IJLINK ioctl(2), 
see streamio(7)]. 

Initial number of internal event cells available in system to 
support bufcall (see Appendix C) and poll (2) calls. 

The number of additional pages of memory that can be 
dynamically allocated for event cells. If this value is 0, only 
the allocation defined by NSTREVENT is available for use. 

If the value is not 0 and if the kernel runs out of event cells, 
it will under some circumstances attempt to allocate an extra 
page of memory from which new event cells can be created. 
MAXSEPGCNT places a limit on the number of pages that 
can be allocated for this purpose. Once a page has been allo- 
cated for event cells, however, it cannot be recovered later for 
use elsewhere. 

Maximum number of modules that may be pushed onto a sin- 
gle Stream. 

Maximum bytes of information that a single system call can 
pass to a Stream to be placed into the data part of a message 
(in M_DATA blocks). Any write (2) exceeding this size will 
be broken into multiple messages. A putmsg(2) with a data 
part exceeding this size will fail. 
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STRCTLSZ Maximum bytes of information that a single system call can 

pass to a Stream to be placed into the control part of a mes- 
sage (in an M PROTO or M PCPROTO block). A 
putmsg(2) with a control part exceeding this size will fail. 

STRLOFRAC The percentage of data blocks of a given class at which low 
^priority block allocation requests are automatically failed. 

For example, if STRLOFRAC is 80 and there are 48 256- 
byte blocks, a low priority allocation request will fail when 
more than 38 256-byte blocks are already allocated. This 
value is used to prevent deadlock situations in which a low 
priority activity might starve out more important functions. 
For example, if STRLOFRAC is 80 and there are 100 blocks 
of 256 bytes, then when more than 80 of such blocks are allo- 
cated, any low priority allocation request will fail. This value 
must be in the range 

0 <= STRLOFRAC <= STRMEDFRAC. 

STRMEDFRAC The percentage of data blocks of a given class at which 

medium priority block allocation requests are automatically 
failed. 



System Error Messages 

Messages are reported to the console as a result of various error conditions 
detected by STREAMS. These messages and the action to be taken on their 
occurrence are described below. In certain cases, a tunable parameter (see previ- 
ous section) may have to be changed. 

stropen: out of streams 

A Stream head data structure could not be allocated during the open of 
a STREAMS device. If this occurs repeatedly, increase NSTREAM. 

stropen: out of queues 

A pair of queues could not be allocated for the Stream head during the 
open of a driver. If this occurs repeatedly, increase NQUEUE. 

KERNEL: allocq: out of queues 

A pair of queues could not be allocated for a pushable module 
(I_PUSH ioctl) or driver (open) . If this occurs repeatedly, increase 
NQUEUE. 
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strinit: can not allocate stream data blocks 

During system initialization, the system was unable to allocate enough 
memory for the STREAMS data blocks. The system must be rebuilt 
with fewer data blocks specified. 

KERNEL: strinit: odd value configured for v.vnqueue 
KERNEL: strinit: was qcnt , set to nqcnt 

During system initialization, the total number of queues allocated, qcnt , 
was not a multiple of 2. The system resets this to an appropriate value, 
nqcnt. 

WARNING: bufcall: could not allocate stream event 

A call to bufcall has failed because all Stream event cells have been 
allocated. If this occurs repeatedly, increase NSTREVENT. 

KERNEL: sealloc: not enough memory for page allocation 

An attempt to dynamically allocate a page of Stream event cells failed. 
If this occurs repeatedly, decrease MAXSEPGCNT. 

KERNEL: munlink: could not perform ioctl, closing anyway 

A linked multiplexor could not be unlinked when the controlling Stream 
for that link was closed. The linked Stream will be unlinked and the 
controlling Stream will be closed anyway. 
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Back enable 

Blocked 
Clone device 

Close procedure 

Control stream 



Downstream 
Device driver 



Driver 



Enable 
Flow control 

Lower Stream 



To enable (by STREAMS) a preceding blocked QUEUE 
when STREAMS determines that a succeeding QUEUE 
has reached its low water mark. 

A QUEUE that cannot be enabled due to flow control. 

A STREAMS device that returns an unused minor 
device when initially opened, rather than requiring the 
minor device to be specified in the open (2) call. 

The module routine that is called when a module is 
popped from a Stream and the driver routine that is 
called when a driver is closed. 

In a multiplexor , the upper Stream on which a previous 
I_LINK ioctl [to the associated file, see streamio(7)] 
caused a lower Stream to be connected to the multi- 
plexor driver at the end of the upper Stream. 

The direction from Stream head towards driver. 

The end of the Stream closest to an external interface. 
The principle functions of a device driver are handling 
an associated physical device, and transforming data and 
information between the external interface and Stream. 

A module that forms the Stream end. It can be a device 
driver or a pseudo -device driver. In STREAMS, a 
driver is physically identical to a module (i.e., composed 
of two QUEUEs), but has additional attributes in a 
Stream and in the UNIX system. 

Schedule a QUEUE. 

The STREAMS mechanism that regulates the flow of 
messages within a Stream and the flow from user space 
into a Stream. 

A Stream connected below a multiplexor pseudo-device 
driver , by means of an I_LINK ioctl. The far end of a 
lower Stream terminates at a device driver or another 
multiplexor driver. 
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Message 
Message block 

Message queue 
Message type 
Module 
Multiplexor 

Open procedure 
Pop 

Pseudo-device driver 
Push 



One or more linked message blocks. A message is refer- 
enced by its first message block and its type is defined by 
the message type of that block. 

Carries data or information, as identified by its message 
type , in a Stream. A message block is a triplet consist- 
ing of a data buffer and associated control structures, an 
mblkt structure and a dblk t structure. 

A linked list of zero or more messages connected to a 
QUEUE. 

A defined set of values identifying the contents of a mes- 
sage block and message. 

A pair of QUEUES. In general, module implies a push - 
able module. 

A STREAMS mechanism that allows messages to be 
routed among multiple Streams in the kernel. A multi- 
plexor includes at least one multiplexing pseudo-device 
driver connected to one or more upper Streams and one 
or more lower Streams. 

The routine in each STREAMS driver and module 
called by STREAMS on each open (2) system call made 
on the Stream. A module's open procedure is also called 
when the module is pushed. 

A STREAMS ioctl [see streamio(7)l that causes the 
pushable module immediately below the Stream head to 
be removed (popped) from a Stream [modules can also 
be popped as the result of a close (2)1. 



A software driver , not directly associated with a physical 
device, that performs functions internal to a Stream such 
as a multiplexor or log driver. 

A STREAMS ioctl [see streamio(7)l that causes a 
pushable module to be inserted (pushed) in a Stream 
immediately below the Stream head. 
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Pushable module 



Put procedure 



QUEUE 



Read queue 



Schedule 



Service interface 



A module interposed (pushed) between the Stream head 
and driver. Pushable modules perform intermediate 
transformations on messages flowing between the Stream 
head and driver. A driver is a non-pushable module and 
a Stream head includes a non-pushable module. 

The routine in a QUEUE which receives messages from 
the preceding QUEUE. It is the single entry point into 
a QUEUE from a preceding QUEUE. The procedure 
may perform processing on the message and will then 
generally either queue the message for subsequent pro- 
cessing by this QUEUE’S service procedure , or will pass 
the message to the put procedure of the following 
QUEUE. 

A STREAMS defined set of C-language structures. A 
module is composed of a read ( upstream ) QUEUE and 
a write ( downstream ) QUEUE. A QUEUE will typi- 
cally contain a put and service procedure, a message 
queue , and private data. The read QUEUE (cf. read 
queue) in a module will also contain the open procedure 
and close procedure for the module. 

The primary structure is the queue t structure, occasion- 
ally used as a synonym for a QUEUE. 

The message queue in a module or driver containing 
messages moving upstream. Associated with a read (2) 
system call and input from a driver. 

Place a QUEUE on the internal list of QUEUES which 
will subsequently have their service procedure called by 
the STREAMS scheduler. 

A set of primitives that define a service at the boundary 
between a service user and a service provider and the 
rules (typically represented by a state machine) for 
allowable sequences of the primitives across the boun- 
dary. At a Stream/user boundary, the primitives are 
typically contained in the control part of a message; 
within a Stream, in MPROTO or M PCPROTO mes- 
sage blocks. 
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Service procedure 

Service provider 
Service user 
Stream 

Stream end 
Stream head 

STREAMS 
Upper stream 



The routine in a QUEUE which receives messages 
queued for it by the put procedure of the QUEUE. The 
procedure is called by the STREAMS scheduler. It 
may perform processing on the message and will gen- 
erally pass the message to the put procedure of the fol- 
lowing QUEUE. 

In a service interface , the entity (typically a module or 
driver) that responds to request primitives from the ser- 
vice user with response and event primitives. 

In a service interface , the entity that generates request 
primitives for the service provider and consumes 
response and event primitives. 

The kernel aggregate created by connecting STREAMS 
components, resulting from an application of the 
STREAMS mechanism. The primary components are 
the Stream head , the driver , and zero or more pushable 
modules between the Stream head and driver. 

The end of the Stream furthest from the user process, 
containing a driver. 

The end of the Stream closest to the user process. It 
provides the interface between the Stream and the user 
process. 

A kernel mechanism that supports development of net- 
work services and data communication drivers. It 
defines interface standards for character input/output 
within the kernel, and between the kernel and user level. 
The STREAMS mechanism comprises integral func- 
tions, utility routines, kernel facilities and a set of struc- 
tures. 

A Stream terminating above a multiplexor pseudo-device 
driver. The far end of an upper Stream originates at the 
Stream head or another multiplexor driver. 
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Upstream 
Water marks 



Write queue 



The direction from driver towards Stream head. 

Limit values used in flow control. Each QUEUE has a 
high water mark and a low water mark. The high water 
mark value indicates the upper limit related to the 
number of characters contained on the message queue of 
a QUEUE. When the enqueued characters in a 
QUEUE reach its high water mark, STREAMS causes 
another QUEUE that attempts to send a message to this 
QUEUE to become blocked. When the characters in 
this QUEUE are reduced to the low water mark value, 
the other QUEUE will be unblocked by STREAMS. 

The message queue in a module or driver containing 
messages moving downstream. Associated with a 
write(2) system call and output from a user process. 
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